mongo-driver

module
v1.17.1 Latest Latest
Warning

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

Go to latest
Published: Oct 1, 2024 License: Apache-2.0

README

docs docs

MongoDB Go Driver

The MongoDB supported driver for Go.

[!NOTE]

Go Driver 1.17.0 is the last planned 1.x version. It will receive critical bug fixes, but future development and features will be in the 2.x version of the driver.


Requirements

  • Go 1.18 or higher. We aim to support the latest versions of Go.
  • Go 1.22 or higher is required to run the driver test suite.
  • MongoDB 3.6 and higher.

Installation

The recommended way to get started using the MongoDB Go driver is by using Go modules to install the dependency in your project. This can be done either by importing packages from go.mongodb.org/mongo-driver and having the build step install the dependency or by explicitly running

go get go.mongodb.org/mongo-driver/mongo

When using a version of Go that does not support modules, the driver can be installed using dep by running

dep ensure -add "go.mongodb.org/mongo-driver/mongo"

Usage

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

import (
    "context"
    "time"

    "go.mongodb.org/mongo-driver/mongo"
    "go.mongodb.org/mongo-driver/mongo/options"
    "go.mongodb.org/mongo-driver/mongo/readpref"
)

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
client, err := mongo.Connect(ctx, options.Client().ApplyURI("mongodb://localhost:27017"))

Make sure to defer a call to Disconnect after instantiating your client:

defer func() {
    if err = client.Disconnect(ctx); err != nil {
        panic(err)
    }
}()

For more advanced configuration and authentication, see the documentation for mongo.Connect.

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, cancel = context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()
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, cancel = context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
res, err := collection.InsertOne(ctx, bson.D{{"name", "pi"}, {"value", 3.14159}})
id := res.InsertedID

To use bson.D, you will need to add "go.mongodb.org/mongo-driver/bson" to your imports.

Your import statement should now look like this:

import (
    "context"
    "log"
    "time"

    "go.mongodb.org/mongo-driver/bson"
    "go.mongodb.org/mongo-driver/mongo"
    "go.mongodb.org/mongo-driver/mongo/options"
    "go.mongodb.org/mongo-driver/mongo/readpref"
)

Several query methods return a cursor, which can be used like this:

ctx, cancel = context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
cur, err := collection.Find(ctx, bson.D{})
if err != nil { log.Fatal(err) }
defer cur.Close(ctx)
for cur.Next(ctx) {
    var result bson.D
    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.D{{"name", "pi"}}
ctx, cancel = context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
err = collection.FindOne(ctx, filter).Decode(&result)
if err == mongo.ErrNoDocuments {
    // Do something when no record was found
    fmt.Println("record does not exist")
} else 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.

Network Compression

Network compression will reduce bandwidth requirements between MongoDB and the application.

The Go Driver supports the following compression algorithms:

  1. Snappy (snappy): available in MongoDB 3.4 and later.
  2. Zlib (zlib): available in MongoDB 3.6 and later.
  3. Zstandard (zstd): available in MongoDB 4.2 and later.
Specify Compression Algorithms

Compression can be enabled using the compressors parameter on the connection string or by using ClientOptions.SetCompressors:

opts := options.Client().ApplyURI("mongodb://localhost:27017/?compressors=snappy,zlib,zstd")
client, _ := mongo.Connect(context.TODO(), opts)
opts := options.Client().SetCompressors([]string{"snappy", "zlib", "zstd"})
client, _ := mongo.Connect(context.TODO(), opts)

If compressors are set, the Go Driver negotiates with the server to select the first common compressor. For server configuration and defaults, refer to networkMessageCompressors.

Messages compress when both parties enable network compression; otherwise, messages remain uncompressed


Feedback

For help with the driver, please post in the MongoDB Community Forums.

New features and bugs can be reported on jira: https://jira.mongodb.org/browse/GODRIVER


Contribution

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.


Frequently Encountered Issues

See our common issues documentation for troubleshooting frequently encountered issues.


Thanks and Acknowledgement


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.
bsonoptions
Package bsonoptions defines the optional configurations for the BSON codecs.
Package bsonoptions defines the optional configurations for the BSON codecs.
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.
bsonrw/bsonrwtest
Package bsonrwtest provides utilities for testing the "bson/bsonrw" package.
Package bsonrwtest provides utilities for testing the "bson/bsonrw" package.
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.
mgocompat
Package mgocompat provides Registry, a BSON registry compatible with globalsign/mgo's BSON, with some remaining differences.
Package mgocompat provides Registry, a BSON registry compatible with globalsign/mgo's BSON, with some remaining differences.
primitive
Package primitive contains types similar to Go primitives for BSON types that do not have direct Go primitive representations.
Package primitive contains types similar to Go primitives for BSON types that do not have direct Go primitive representations.
cmd
build-oss-fuzz-corpus
Entry point for the MongoDB Go Driver integration into the Google "oss-fuzz" project (https://github.com/google/oss-fuzz).
Entry point for the MongoDB Go Driver integration into the Google "oss-fuzz" project (https://github.com/google/oss-fuzz).
Package event is a library for monitoring events from the MongoDB Go driver.
Package event is a library for monitoring events from the MongoDB Go driver.
examples
internal
aws
aws/awserr
Package awserr represents API error interface accessors for the SDK.
Package awserr represents API error interface accessors for the SDK.
eventtest
Package eventtest provides test types that are used to monitor client state and actions via the various monitor types supported by the driver.
Package eventtest provides test types that are used to monitor client state and actions via the various monitor types supported by the driver.
israce
Package israce reports if the Go race detector is enabled.
Package israce reports if the Go race detector is enabled.
logger
Package logger provides the internal logging solution for the MongoDB Go Driver.
Package logger provides the internal logging solution for the MongoDB Go Driver.
rand
Package rand implements pseudo-random number generators.
Package rand implements pseudo-random number generators.
randutil
Package randutil provides common random number utilities.
Package randutil provides common random number utilities.
Package mongo provides a MongoDB Driver API for Go.
Package mongo provides a MongoDB Driver API for Go.
address
Package address provides structured representations of network addresses.
Package address provides structured representations of network addresses.
description
Package description contains types and functions for describing the state of MongoDB clusters.
Package description contains types and functions for describing the state of MongoDB clusters.
gridfs
Package gridfs provides a MongoDB GridFS API.
Package gridfs provides a MongoDB GridFS API.
integration/mtest
Package mtest is unstable and there is no backward compatibility guarantee.
Package mtest is unstable and there is no backward compatibility guarantee.
options
Package options defines the optional configurations for the MongoDB Go Driver.
Package options defines the optional configurations for the MongoDB Go Driver.
readconcern
Package readconcern defines read concerns for MongoDB operations.
Package readconcern defines read concerns for MongoDB operations.
readpref
Package readpref defines read preferences for MongoDB queries.
Package readpref defines read preferences for MongoDB queries.
writeconcern
Package writeconcern defines write concerns for MongoDB operations.
Package writeconcern defines write concerns for MongoDB operations.
Package tag provides types for filtering replica set members using tags in a read preference.
Package tag provides types for filtering replica set members using tags in a read preference.
Package version defines the Go Driver version.
Package version defines the Go Driver version.
x
bsonx/bsoncore
Package bsoncore is intended for internal use only.
Package bsoncore is intended for internal use only.
mongo/driver
Package driver is intended for internal use only.
Package driver is intended for internal use only.
mongo/driver/auth
Package auth is intended for internal use only.
Package auth is intended for internal use only.
mongo/driver/auth/creds
Package creds is intended for internal use only.
Package creds is intended for internal use only.
mongo/driver/connstring
Package connstring is intended for internal use only.
Package connstring is intended for internal use only.
mongo/driver/dns
Package dns is intended for internal use only.
Package dns is intended for internal use only.
mongo/driver/drivertest
Package drivertest is intended for internal use only.
Package drivertest is intended for internal use only.
mongo/driver/integration
Package integration is intended for internal use only.
Package integration is intended for internal use only.
mongo/driver/mongocrypt
Package mongocrypt is intended for internal use only.
Package mongocrypt is intended for internal use only.
mongo/driver/mongocrypt/options
Package options is intended for internal use only.
Package options is intended for internal use only.
mongo/driver/ocsp
Package ocsp is intended for internal use only.
Package ocsp is intended for internal use only.
mongo/driver/operation
Package operation is intended for internal use only.
Package operation is intended for internal use only.
mongo/driver/session
Package session is intended for internal use only.
Package session is intended for internal use only.
mongo/driver/topology
Package topology is intended for internal use only.
Package topology is intended for internal use only.
mongo/driver/wiremessage
Package wiremessage is intended for internal use only.
Package wiremessage is intended for internal use only.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL