Documentation ¶
Overview ¶
Package mongo provides a MongoDB Driver API for Go.
Basic usage of the driver starts with creating a Client from a connection string. To do so, call Connect:
ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second) defer cancel() client, err := mongo.Connect( options.Client().ApplyURI("mongodb://foo:bar@localhost:27017")) if err != nil { return err }
This will create a new client and start monitoring the MongoDB server on localhost. The Database and Collection types can be used to access the database:
collection := client.Database("baz").Collection("qux")
A Collection can be used to query the database or insert documents:
res, err := collection.InsertOne(context.Background(), bson.M{"hello": "world"}) if err != nil { return err } id := res.InsertedID
Several methods return a cursor, which can be used like this:
cur, err := collection.Find(context.Background(), bson.D{}) if err != nil { log.Fatal(err) } defer cur.Close(context.Background()) for cur.Next(context.Background()) { // To decode into a struct, use cursor.Decode() result := struct{ Foo string Bar int32 }{} err := cur.Decode(&result) if err != nil { log.Fatal(err) } // do something with result... // To get the raw bson bytes use cursor.Current raw := cur.Current // do something with raw... } if err := cur.Err(); err != nil { return err }
Cursor.All will decode all of the returned elements at once:
var results []struct{ Foo string Bar int32 } if err = cur.All(context.Background(), &results); err != nil { log.Fatal(err) } // do something with results...
Methods that only return a single document will return a *SingleResult, which works like a *sql.Row:
result := struct{ Foo string Bar int32 }{} filter := bson.D{{"hello", "world"}} err := collection.FindOne(context.Background(), filter).Decode(&result) if err != nil { return err } // do something with result...
All Client, Collection, and Database methods that take parameters of type interface{} will return ErrNilDocument if nil is passed in for an interface{}.
Additional examples can be found under the examples directory in the driver's repository and on the MongoDB website.
Error Handling ¶
Errors from the MongoDB server will implement the ServerError interface, which has functions to check for specific error codes, labels, and message substrings. These can be used to check for and handle specific errors. Some methods, like InsertMany and BulkWrite, can return an error representing multiple errors, and in those cases the ServerError functions will return true if any of the contained errors satisfy the check.
There are also helper functions to check for certain specific types of errors:
IsDuplicateKeyError(error) IsNetworkError(error) IsTimeout(error)
Potential DNS Issues ¶
Building with Go 1.11+ and using connection strings with the "mongodb+srv"[1] scheme is unfortunately incompatible with some DNS servers in the wild due to the change introduced in https://github.com/golang/go/issues/10622. You may receive an error with the message "cannot unmarshal DNS message" while running an operation when using DNS servers that non-compliantly compress SRV records. Old versions of kube-dns and the native DNS resolver (systemd-resolver) on Ubuntu 18.04 are known to be non-compliant in this manner. We suggest using a different DNS server (8.8.8.8 is the common default), and, if that's not possible, avoiding the "mongodb+srv" scheme.
Client Side Encryption ¶
Client-side encryption is a new feature in MongoDB 4.2 that allows specific data fields to be encrypted. Using this feature requires specifying the "cse" build tag during compilation:
go build -tags cse
Note: Auto encryption is an enterprise- and Atlas-only feature.
The libmongocrypt C library is required when using client-side encryption. Specific versions of libmongocrypt are required for different versions of the Go Driver:
- Go Driver v1.2.0 requires libmongocrypt v1.0.0 or higher
- Go Driver v1.5.0 requires libmongocrypt v1.1.0 or higher
- Go Driver v1.8.0 requires libmongocrypt v1.3.0 or higher
- Go Driver v1.10.0 requires libmongocrypt v1.5.0 or higher. There is a severe bug when calling RewrapManyDataKey with libmongocrypt versions less than 1.5.2. This bug may result in data corruption. Please use libmongocrypt 1.5.2 or higher when calling RewrapManyDataKey.
- Go Driver v1.12.0 requires libmongocrypt v1.8.0 or higher.
To install libmongocrypt, follow the instructions for your operating system:
1. Linux: follow the instructions listed at https://github.com/mongodb/libmongocrypt#installing-libmongocrypt-from-distribution-packages to install the correct deb/rpm package.
2. Mac: Follow the instructions listed at https://github.com/mongodb/libmongocrypt#installing-libmongocrypt-on-macos to install packages via brew and compile the libmongocrypt source code.
3. Windows:
mkdir -p c:/libmongocrypt/bin mkdir -p c:/libmongocrypt/include // Run the curl command in an empty directory as it will create new directories when unpacked. curl https://s3.amazonaws.com/mciuploads/libmongocrypt/windows/latest_release/libmongocrypt.tar.gz --output libmongocrypt.tar.gz tar -xvzf libmongocrypt.tar.gz cp ./bin/mongocrypt.dll c:/libmongocrypt/bin cp ./include/mongocrypt/*.h c:/libmongocrypt/include export PATH=$PATH:/cygdrive/c/libmongocrypt/bin
libmongocrypt communicates with the mongocryptd process or mongo_crypt shared library for automatic encryption. See AutoEncryptionOpts.SetExtraOptions for options to configure use of mongocryptd or mongo_crypt.
[1] See https://www.mongodb.com/docs/manual/reference/connection-string/#dns-seedlist-connection-format
Example (ClientSideEncryption) ¶
// This would have to be the same master key that was used to create the // encryption key. localKey := make([]byte, 96) if _, err := rand.Read(localKey); err != nil { log.Panic(err) } kmsProviders := map[string]map[string]interface{}{ "local": { "key": localKey, }, } keyVaultNamespace := "encryption.__keyVault" uri := "mongodb://localhost:27017" autoEncryptionOpts := options.AutoEncryption(). SetKeyVaultNamespace(keyVaultNamespace). SetKmsProviders(kmsProviders) clientOpts := options.Client(). ApplyURI(uri). SetAutoEncryptionOptions(autoEncryptionOpts) client, err := Connect(clientOpts) if err != nil { log.Panicf("Connect error: %v", err) } defer func() { if err = client.Disconnect(context.TODO()); err != nil { log.Panicf("Disconnect error: %v", err) } }() collection := client.Database("test").Collection("coll") if err := collection.Drop(context.TODO()); err != nil { log.Panicf("Collection.Drop error: %v", err) } _, err = collection.InsertOne( context.TODO(), bson.D{{"encryptedField", "123456789"}}) if err != nil { log.Panicf("InsertOne error: %v", err) } res, err := collection.FindOne(context.TODO(), bson.D{}).Raw() if err != nil { log.Panicf("FindOne error: %v", err) } fmt.Println(res)
Output:
Example (ClientSideEncryptionCreateKey) ¶
keyVaultNamespace := "encryption.__keyVault" uri := "mongodb://localhost:27017" // kmsProviders would have to be populated with the correct KMS provider // information before it's used. var kmsProviders map[string]map[string]interface{} // Create Client and ClientEncryption clientEncryptionOpts := options.ClientEncryption(). SetKeyVaultNamespace(keyVaultNamespace). SetKmsProviders(kmsProviders) keyVaultClient, err := Connect(options.Client().ApplyURI(uri)) if err != nil { log.Panicf("Connect error for keyVaultClient: %v", err) } clientEnc, err := NewClientEncryption(keyVaultClient, clientEncryptionOpts) if err != nil { log.Panicf("NewClientEncryption error: %v", err) } defer func() { // this will disconnect the keyVaultClient as well if err = clientEnc.Close(context.TODO()); err != nil { log.Panicf("Close error: %v", err) } }() // Create a new data key and encode it as base64 dataKeyID, err := clientEnc.CreateDataKey(context.TODO(), "local") if err != nil { log.Panicf("CreateDataKey error: %v", err) } dataKeyBase64 := base64.StdEncoding.EncodeToString(dataKeyID.Data) // Create a JSON schema using the new data key. This schema could also be // written in a separate file and read in using I/O functions. schema := `{ "properties": { "encryptedField": { "encrypt": { "keyId": [{ "$binary": { "base64": "%s", "subType": "04" } }], "bsonType": "string", "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic" } } }, "bsonType": "object" }` schema = fmt.Sprintf(schema, dataKeyBase64) var schemaDoc bson.Raw err = bson.UnmarshalExtJSON([]byte(schema), true, &schemaDoc) if err != nil { log.Panicf("UnmarshalExtJSON error: %v", err) } // Configure a Client with auto encryption using the new schema dbName := "test" collName := "coll" schemaMap := map[string]interface{}{ dbName + "." + collName: schemaDoc, } autoEncryptionOpts := options.AutoEncryption(). SetKmsProviders(kmsProviders). SetKeyVaultNamespace(keyVaultNamespace). SetSchemaMap(schemaMap) clientOptions := options.Client(). ApplyURI(uri). SetAutoEncryptionOptions(autoEncryptionOpts) client, err := Connect(clientOptions) if err != nil { log.Panicf("Connect error for encrypted client: %v", err) } defer func() { _ = client.Disconnect(context.TODO()) }() // Use client for operations.
Output:
Example (ExplictEncryption) ¶
// localMasterKey must be the same master key that was used to create the // encryption key. var localMasterKey []byte kmsProviders := map[string]map[string]interface{}{ "local": { "key": localMasterKey, }, } // The MongoDB namespace (db.collection) used to store the encryption data // keys. keyVaultDBName, keyVaultCollName := "encryption", "testKeyVault" keyVaultNamespace := keyVaultDBName + "." + keyVaultCollName // The Client used to read/write application data. opts := options.Client().ApplyURI("mongodb://localhost:27017") client, err := Connect(opts) if err != nil { panic(err) } defer func() { _ = client.Disconnect(context.TODO()) }() // Get a handle to the application collection and clear existing data. coll := client.Database("test").Collection("coll") _ = coll.Drop(context.TODO()) // Set up the key vault for this example. keyVaultColl := client.Database(keyVaultDBName).Collection(keyVaultCollName) _ = keyVaultColl.Drop(context.TODO()) // Ensure that two data keys cannot share the same keyAltName. keyVaultIndex := IndexModel{ Keys: bson.D{{"keyAltNames", 1}}, Options: options.Index(). SetUnique(true). SetPartialFilterExpression(bson.D{ {"keyAltNames", bson.D{ {"$exists", true}, }}, }), } _, err = keyVaultColl.Indexes().CreateOne(context.TODO(), keyVaultIndex) if err != nil { panic(err) } // Create the ClientEncryption object to use for explicit // encryption/decryption. The Client passed to NewClientEncryption is used // to read/write to the key vault. This can be the same Client used by the // main application. clientEncryptionOpts := options.ClientEncryption(). SetKmsProviders(kmsProviders). SetKeyVaultNamespace(keyVaultNamespace) clientEncryption, err := NewClientEncryption(client, clientEncryptionOpts) if err != nil { panic(err) } defer func() { _ = clientEncryption.Close(context.TODO()) }() // Create a new data key for the encrypted field. dataKeyOpts := options.DataKey(). SetKeyAltNames([]string{"go_encryption_example"}) dataKeyID, err := clientEncryption.CreateDataKey( context.TODO(), "local", dataKeyOpts) if err != nil { panic(err) } // Create a bson.RawValue to encrypt and encrypt it using the key that was // just created. rawValueType, rawValueData, err := bson.MarshalValue("123456789") if err != nil { panic(err) } rawValue := bson.RawValue{Type: rawValueType, Value: rawValueData} encryptionOpts := options.Encrypt(). SetAlgorithm("AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"). SetKeyID(dataKeyID) encryptedField, err := clientEncryption.Encrypt( context.TODO(), rawValue, encryptionOpts) if err != nil { panic(err) } // Insert a document with the encrypted field and then find it. _, err = coll.InsertOne( context.TODO(), bson.D{{"encryptedField", encryptedField}}) if err != nil { panic(err) } var foundDoc bson.M err = coll.FindOne(context.TODO(), bson.D{}).Decode(&foundDoc) if err != nil { panic(err) } // Decrypt the encrypted field in the found document. decrypted, err := clientEncryption.Decrypt( context.TODO(), foundDoc["encryptedField"].(bson.Binary)) if err != nil { panic(err) } fmt.Printf("Decrypted value: %s\n", decrypted)
Output:
Example (ExplictEncryptionWithAutomaticDecryption) ¶
// Automatic encryption requires MongoDB 4.2 enterprise, but automatic // decryption is supported for all users. // localMasterKey must be the same master key that was used to create the // encryption key. var localMasterKey []byte kmsProviders := map[string]map[string]interface{}{ "local": { "key": localMasterKey, }, } // The MongoDB namespace (db.collection) used to store the encryption data // keys. keyVaultDBName, keyVaultCollName := "encryption", "testKeyVault" keyVaultNamespace := keyVaultDBName + "." + keyVaultCollName // Create the Client for reading/writing application data. Configure it with // BypassAutoEncryption=true to disable automatic encryption but keep // automatic decryption. Setting BypassAutoEncryption will also bypass // spawning mongocryptd in the driver. autoEncryptionOpts := options.AutoEncryption(). SetKmsProviders(kmsProviders). SetKeyVaultNamespace(keyVaultNamespace). SetBypassAutoEncryption(true) clientOpts := options.Client(). ApplyURI("mongodb://localhost:27017"). SetAutoEncryptionOptions(autoEncryptionOpts) client, err := Connect(clientOpts) if err != nil { panic(err) } defer func() { _ = client.Disconnect(context.TODO()) }() // Get a handle to the application collection and clear existing data. coll := client.Database("test").Collection("coll") _ = coll.Drop(context.TODO()) // Set up the key vault for this example. keyVaultColl := client.Database(keyVaultDBName).Collection(keyVaultCollName) _ = keyVaultColl.Drop(context.TODO()) // Ensure that two data keys cannot share the same keyAltName. keyVaultIndex := IndexModel{ Keys: bson.D{{"keyAltNames", 1}}, Options: options.Index(). SetUnique(true). SetPartialFilterExpression(bson.D{ {"keyAltNames", bson.D{ {"$exists", true}, }}, }), } _, err = keyVaultColl.Indexes().CreateOne(context.TODO(), keyVaultIndex) if err != nil { panic(err) } // Create the ClientEncryption object to use for explicit // encryption/decryption. The Client passed to NewClientEncryption is used // to read/write to the key vault. This can be the same Client used by the // main application. clientEncryptionOpts := options.ClientEncryption(). SetKmsProviders(kmsProviders). SetKeyVaultNamespace(keyVaultNamespace) clientEncryption, err := NewClientEncryption(client, clientEncryptionOpts) if err != nil { panic(err) } defer func() { _ = clientEncryption.Close(context.TODO()) }() // Create a new data key for the encrypted field. dataKeyOpts := options.DataKey(). SetKeyAltNames([]string{"go_encryption_example"}) dataKeyID, err := clientEncryption.CreateDataKey( context.TODO(), "local", dataKeyOpts) if err != nil { panic(err) } // Create a bson.RawValue to encrypt and encrypt it using the key that was // just created. rawValueType, rawValueData, err := bson.MarshalValue("123456789") if err != nil { panic(err) } rawValue := bson.RawValue{Type: rawValueType, Value: rawValueData} encryptionOpts := options.Encrypt(). SetAlgorithm("AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"). SetKeyID(dataKeyID) encryptedField, err := clientEncryption.Encrypt( context.TODO(), rawValue, encryptionOpts) if err != nil { panic(err) } // Insert a document with the encrypted field and then find it. The FindOne // call will automatically decrypt the field in the document. _, err = coll.InsertOne( context.TODO(), bson.D{{"encryptedField", encryptedField}}) if err != nil { panic(err) } var foundDoc bson.M err = coll.FindOne(context.TODO(), bson.D{}).Decode(&foundDoc) if err != nil { panic(err) } fmt.Printf("Decrypted document: %v\n", foundDoc)
Output:
Index ¶
- Constants
- Variables
- func BatchCursorFromCursor(c *Cursor) *driver.BatchCursordeprecated
- func IsDuplicateKeyError(err error) bool
- func IsNetworkError(err error) bool
- func IsTimeout(err error) bool
- func NewSessionContext(parent context.Context, sess *Session) context.Context
- func WithSession(ctx context.Context, sess *Session, fn func(context.Context) error) error
- type BulkWriteError
- type BulkWriteException
- func (bwe BulkWriteException) Error() string
- func (bwe BulkWriteException) HasErrorCode(code int) bool
- func (bwe BulkWriteException) HasErrorCodeWithMessage(code int, message string) bool
- func (bwe BulkWriteException) HasErrorLabel(label string) bool
- func (bwe BulkWriteException) HasErrorMessage(message string) bool
- type BulkWriteResult
- type ChangeStream
- func (cs *ChangeStream) Close(ctx context.Context) error
- func (cs *ChangeStream) Decode(val interface{}) error
- func (cs *ChangeStream) Err() error
- func (cs *ChangeStream) ID() int64
- func (cs *ChangeStream) Next(ctx context.Context) bool
- func (cs *ChangeStream) RemainingBatchLength() int
- func (cs *ChangeStream) ResumeToken() bson.Raw
- func (cs *ChangeStream) SetBatchSize(size int32)
- func (cs *ChangeStream) TryNext(ctx context.Context) bool
- type Client
- func (c *Client) Database(name string, opts ...options.Lister[options.DatabaseOptions]) *Database
- func (c *Client) Disconnect(ctx context.Context) error
- func (c *Client) ListDatabaseNames(ctx context.Context, filter interface{}, ...) ([]string, error)
- func (c *Client) ListDatabases(ctx context.Context, filter interface{}, ...) (ListDatabasesResult, error)
- func (c *Client) NumberSessionsInProgress() int
- func (c *Client) Ping(ctx context.Context, rp *readpref.ReadPref) error
- func (c *Client) StartSession(opts ...options.Lister[options.SessionOptions]) (*Session, error)
- func (c *Client) UseSession(ctx context.Context, fn func(context.Context) error) error
- func (c *Client) UseSessionWithOptions(ctx context.Context, opts *options.SessionOptionsBuilder, ...) error
- func (c *Client) Watch(ctx context.Context, pipeline interface{}, ...) (*ChangeStream, error)
- type ClientEncryption
- func (ce *ClientEncryption) AddKeyAltName(ctx context.Context, id bson.Binary, keyAltName string) *SingleResult
- func (ce *ClientEncryption) Close(ctx context.Context) error
- func (ce *ClientEncryption) CreateDataKey(ctx context.Context, kmsProvider string, ...) (bson.Binary, error)
- func (ce *ClientEncryption) CreateEncryptedCollection(ctx context.Context, db *Database, coll string, ...) (*Collection, bson.M, error)
- func (ce *ClientEncryption) Decrypt(ctx context.Context, val bson.Binary) (bson.RawValue, error)
- func (ce *ClientEncryption) DeleteKey(ctx context.Context, id bson.Binary) (*DeleteResult, error)
- func (ce *ClientEncryption) Encrypt(ctx context.Context, val bson.RawValue, ...) (bson.Binary, error)
- func (ce *ClientEncryption) EncryptExpression(ctx context.Context, expr interface{}, result interface{}, ...) error
- func (ce *ClientEncryption) GetKey(ctx context.Context, id bson.Binary) *SingleResult
- func (ce *ClientEncryption) GetKeyByAltName(ctx context.Context, keyAltName string) *SingleResult
- func (ce *ClientEncryption) GetKeys(ctx context.Context) (*Cursor, error)
- func (ce *ClientEncryption) RemoveKeyAltName(ctx context.Context, id bson.Binary, keyAltName string) *SingleResult
- func (ce *ClientEncryption) RewrapManyDataKey(ctx context.Context, filter interface{}, ...) (*RewrapManyDataKeyResult, error)
- type Collection
- func (coll *Collection) Aggregate(ctx context.Context, pipeline interface{}, ...) (*Cursor, error)
- func (coll *Collection) BulkWrite(ctx context.Context, models []WriteModel, ...) (*BulkWriteResult, error)
- func (coll *Collection) Clone(opts ...options.Lister[options.CollectionOptions]) *Collection
- func (coll *Collection) CountDocuments(ctx context.Context, filter interface{}, ...) (int64, error)
- func (coll *Collection) Database() *Database
- func (coll *Collection) DeleteMany(ctx context.Context, filter interface{}, ...) (*DeleteResult, error)
- func (coll *Collection) DeleteOne(ctx context.Context, filter interface{}, ...) (*DeleteResult, error)
- func (coll *Collection) Distinct(ctx context.Context, fieldName string, filter interface{}, ...) *DistinctResult
- func (coll *Collection) Drop(ctx context.Context, opts ...options.Lister[options.DropCollectionOptions]) error
- func (coll *Collection) EstimatedDocumentCount(ctx context.Context, ...) (int64, error)
- func (coll *Collection) Find(ctx context.Context, filter interface{}, ...) (*Cursor, error)
- func (coll *Collection) FindOne(ctx context.Context, filter interface{}, ...) *SingleResult
- func (coll *Collection) FindOneAndDelete(ctx context.Context, filter interface{}, ...) *SingleResult
- func (coll *Collection) FindOneAndReplace(ctx context.Context, filter interface{}, replacement interface{}, ...) *SingleResult
- func (coll *Collection) FindOneAndUpdate(ctx context.Context, filter interface{}, update interface{}, ...) *SingleResult
- func (coll *Collection) Indexes() IndexView
- func (coll *Collection) InsertMany(ctx context.Context, documents interface{}, ...) (*InsertManyResult, error)
- func (coll *Collection) InsertOne(ctx context.Context, document interface{}, ...) (*InsertOneResult, error)
- func (coll *Collection) Name() string
- func (coll *Collection) ReplaceOne(ctx context.Context, filter interface{}, replacement interface{}, ...) (*UpdateResult, error)
- func (coll *Collection) SearchIndexes() SearchIndexView
- func (coll *Collection) UpdateByID(ctx context.Context, id interface{}, update interface{}, ...) (*UpdateResult, error)
- func (coll *Collection) UpdateMany(ctx context.Context, filter interface{}, update interface{}, ...) (*UpdateResult, error)
- func (coll *Collection) UpdateOne(ctx context.Context, filter interface{}, update interface{}, ...) (*UpdateResult, error)
- func (coll *Collection) Watch(ctx context.Context, pipeline interface{}, ...) (*ChangeStream, error)
- type CollectionSpecification
- type CommandError
- func (e CommandError) Error() string
- func (e CommandError) HasErrorCode(code int) bool
- func (e CommandError) HasErrorCodeWithMessage(code int, message string) bool
- func (e CommandError) HasErrorLabel(label string) bool
- func (e CommandError) HasErrorMessage(message string) bool
- func (e CommandError) IsMaxTimeMSExpiredError() bool
- func (e CommandError) Unwrap() error
- type Cursor
- func (c *Cursor) All(ctx context.Context, results interface{}) error
- func (c *Cursor) Close(ctx context.Context) error
- func (c *Cursor) Decode(val interface{}) error
- func (c *Cursor) Err() error
- func (c *Cursor) ID() int64
- func (c *Cursor) Next(ctx context.Context) bool
- func (c *Cursor) RemainingBatchLength() int
- func (c *Cursor) SetBatchSize(batchSize int32)
- func (c *Cursor) SetComment(comment interface{})
- func (c *Cursor) SetMaxAwaitTime(dur time.Duration)
- func (c *Cursor) TryNext(ctx context.Context) bool
- type Database
- func (db *Database) Aggregate(ctx context.Context, pipeline interface{}, ...) (*Cursor, error)
- func (db *Database) Client() *Client
- func (db *Database) Collection(name string, opts ...options.Lister[options.CollectionOptions]) *Collection
- func (db *Database) CreateCollection(ctx context.Context, name string, ...) error
- func (db *Database) CreateView(ctx context.Context, viewName, viewOn string, pipeline interface{}, ...) error
- func (db *Database) Drop(ctx context.Context) error
- func (db *Database) GridFSBucket(opts ...options.Lister[options.BucketOptions]) *GridFSBucket
- func (db *Database) ListCollectionNames(ctx context.Context, filter interface{}, ...) ([]string, error)
- func (db *Database) ListCollectionSpecifications(ctx context.Context, filter interface{}, ...) ([]CollectionSpecification, error)
- func (db *Database) ListCollections(ctx context.Context, filter interface{}, ...) (*Cursor, error)
- func (db *Database) Name() string
- func (db *Database) RunCommand(ctx context.Context, runCommand interface{}, ...) *SingleResult
- func (db *Database) RunCommandCursor(ctx context.Context, runCommand interface{}, ...) (*Cursor, error)
- func (db *Database) Watch(ctx context.Context, pipeline interface{}, ...) (*ChangeStream, error)
- type DatabaseSpecification
- type DeleteManyModel
- type DeleteOneModel
- type DeleteResult
- type Dialer
- type DistinctResult
- type EncryptionKeyVaultError
- type ErrMapForOrderedArgument
- type GridFSBucket
- func (b *GridFSBucket) Delete(ctx context.Context, fileID interface{}) error
- func (b *GridFSBucket) DownloadToStream(ctx context.Context, fileID interface{}, stream io.Writer) (int64, error)
- func (b *GridFSBucket) DownloadToStreamByName(ctx context.Context, filename string, stream io.Writer, ...) (int64, error)
- func (b *GridFSBucket) Drop(ctx context.Context) error
- func (b *GridFSBucket) Find(ctx context.Context, filter interface{}, ...) (*Cursor, error)
- func (b *GridFSBucket) GetChunksCollection() *Collection
- func (b *GridFSBucket) GetFilesCollection() *Collection
- func (b *GridFSBucket) OpenDownloadStream(ctx context.Context, fileID interface{}) (*GridFSDownloadStream, error)
- func (b *GridFSBucket) OpenDownloadStreamByName(ctx context.Context, filename string, ...) (*GridFSDownloadStream, error)
- func (b *GridFSBucket) OpenUploadStream(ctx context.Context, filename string, ...) (*GridFSUploadStream, error)
- func (b *GridFSBucket) OpenUploadStreamWithID(ctx context.Context, fileID interface{}, filename string, ...) (*GridFSUploadStream, error)
- func (b *GridFSBucket) Rename(ctx context.Context, fileID interface{}, newFilename string) error
- func (b *GridFSBucket) UploadFromStream(ctx context.Context, filename string, source io.Reader, ...) (bson.ObjectID, error)
- func (b *GridFSBucket) UploadFromStreamWithID(ctx context.Context, fileID interface{}, filename string, source io.Reader, ...) error
- type GridFSDownloadStream
- type GridFSFile
- type GridFSUploadStream
- type IndexModel
- type IndexSpecification
- type IndexView
- func (iv IndexView) CreateMany(ctx context.Context, models []IndexModel, ...) ([]string, error)
- func (iv IndexView) CreateOne(ctx context.Context, model IndexModel, ...) (string, error)
- func (iv IndexView) DropAll(ctx context.Context, opts ...options.Lister[options.DropIndexesOptions]) error
- func (iv IndexView) DropOne(ctx context.Context, name string, ...) error
- func (iv IndexView) DropWithKey(ctx context.Context, keySpecDocument interface{}, ...) error
- func (iv IndexView) List(ctx context.Context, opts ...options.Lister[options.ListIndexesOptions]) (*Cursor, error)
- func (iv IndexView) ListSpecifications(ctx context.Context, opts ...options.Lister[options.ListIndexesOptions]) ([]IndexSpecification, error)
- type InsertManyResult
- type InsertOneModel
- type InsertOneResult
- type LabeledError
- type ListDatabasesResult
- type MarshalError
- type MongocryptError
- type MongocryptdError
- type Pipeline
- type ReplaceOneModel
- func (rom *ReplaceOneModel) SetCollation(collation *options.Collation) *ReplaceOneModel
- func (rom *ReplaceOneModel) SetFilter(filter interface{}) *ReplaceOneModel
- func (rom *ReplaceOneModel) SetHint(hint interface{}) *ReplaceOneModel
- func (rom *ReplaceOneModel) SetReplacement(rep interface{}) *ReplaceOneModel
- func (rom *ReplaceOneModel) SetUpsert(upsert bool) *ReplaceOneModel
- type RewrapManyDataKeyResult
- type SearchIndexModel
- type SearchIndexView
- func (siv SearchIndexView) CreateMany(ctx context.Context, models []SearchIndexModel, ...) ([]string, error)
- func (siv SearchIndexView) CreateOne(ctx context.Context, model SearchIndexModel, ...) (string, error)
- func (siv SearchIndexView) DropOne(ctx context.Context, name string, ...) error
- func (siv SearchIndexView) List(ctx context.Context, ...) (*Cursor, error)
- func (siv SearchIndexView) UpdateOne(ctx context.Context, name string, definition interface{}, ...) error
- type ServerError
- type Session
- func (s *Session) AbortTransaction(ctx context.Context) error
- func (s *Session) AdvanceClusterTime(d bson.Raw) error
- func (s *Session) AdvanceOperationTime(ts *bson.Timestamp) error
- func (s *Session) Client() *Client
- func (s *Session) ClientSession() *session.Clientdeprecated
- func (s *Session) ClusterTime() bson.Raw
- func (s *Session) CommitTransaction(ctx context.Context) error
- func (s *Session) EndSession(ctx context.Context)
- func (s *Session) ID() bson.Raw
- func (s *Session) OperationTime() *bson.Timestamp
- func (s *Session) StartTransaction(opts ...options.Lister[options.TransactionOptions]) error
- func (s *Session) WithTransaction(ctx context.Context, fn func(ctx context.Context) (interface{}, error), ...) (interface{}, error)
- type SingleResult
- type StreamType
- type UpdateManyModel
- func (umm *UpdateManyModel) SetArrayFilters(filters []interface{}) *UpdateManyModel
- func (umm *UpdateManyModel) SetCollation(collation *options.Collation) *UpdateManyModel
- func (umm *UpdateManyModel) SetFilter(filter interface{}) *UpdateManyModel
- func (umm *UpdateManyModel) SetHint(hint interface{}) *UpdateManyModel
- func (umm *UpdateManyModel) SetUpdate(update interface{}) *UpdateManyModel
- func (umm *UpdateManyModel) SetUpsert(upsert bool) *UpdateManyModel
- type UpdateOneModel
- func (uom *UpdateOneModel) SetArrayFilters(filters []interface{}) *UpdateOneModel
- func (uom *UpdateOneModel) SetCollation(collation *options.Collation) *UpdateOneModel
- func (uom *UpdateOneModel) SetFilter(filter interface{}) *UpdateOneModel
- func (uom *UpdateOneModel) SetHint(hint interface{}) *UpdateOneModel
- func (uom *UpdateOneModel) SetUpdate(update interface{}) *UpdateOneModel
- func (uom *UpdateOneModel) SetUpsert(upsert bool) *UpdateOneModel
- type UpdateResult
- type WriteConcernError
- type WriteError
- type WriteErrors
- type WriteException
- type WriteModel
- Bugs
Examples ¶
- Package (ClientSideEncryption)
- Package (ClientSideEncryptionCreateKey)
- Package (ExplictEncryption)
- Package (ExplictEncryptionWithAutomaticDecryption)
- ChangeStream.Next
- ChangeStream.ResumeToken
- ChangeStream.TryNext
- Client
- Client.ListDatabaseNames
- Client.StartSession (WithTransaction)
- Client.UseSessionWithOptions
- Client.Watch
- Collection.Aggregate
- Collection.BulkWrite
- Collection.CountDocuments
- Collection.DeleteMany
- Collection.DeleteOne
- Collection.Distinct
- Collection.EstimatedDocumentCount
- Collection.Find
- Collection.Find (PrimitiveRegex)
- Collection.Find (Regex)
- Collection.FindOne
- Collection.FindOneAndDelete
- Collection.FindOneAndReplace
- Collection.FindOneAndUpdate
- Collection.InsertMany
- Collection.InsertOne
- Collection.ReplaceOne
- Collection.UpdateMany
- Collection.UpdateOne
- Collection.Watch
- Connect (AWS)
- Connect (BSONOptions)
- Connect (Direct)
- Connect (Kerberos)
- Connect (OIDC)
- Connect (PLAIN)
- Connect (Ping)
- Connect (ReplicaSet)
- Connect (SCRAM)
- Connect (SRV)
- Connect (Sharded)
- Connect (StableAPI)
- Connect (X509)
- Cursor.All
- Cursor.Next
- Cursor.RemainingBatchLength
- Cursor.TryNext
- Database.CreateCollection
- Database.CreateView
- Database.ListCollectionNames
- Database.RunCommand
- Database.Watch
- GridFSBucket.Delete
- GridFSBucket.DownloadToStream
- GridFSBucket.Drop
- GridFSBucket.Find
- GridFSBucket.OpenDownloadStream
- GridFSBucket.OpenUploadStream
- GridFSBucket.Rename
- GridFSBucket.UploadFromStream
- IndexView.CreateMany
- IndexView.List
- NewSessionContext
- WithSession
Constants ¶
const DefaultGridFSChunkSize int32 = 255 * 1024 // 255 KiB
DefaultGridFSChunkSize is the default size of each file chunk.
Variables ¶
var ( // ErrMissingResumeToken indicates that a change stream notification from the server did not contain a resume token. ErrMissingResumeToken = errors.New("cannot provide resume functionality when the resume token is missing") // ErrNilCursor indicates that the underlying cursor for the change stream is nil. ErrNilCursor = errors.New("cursor is nil") )
var ErrClientDisconnected = errors.New("client is disconnected")
ErrClientDisconnected is returned when disconnected Client is used to run an operation.
var ErrEmptySlice = errors.New("must provide at least one element in input slice")
ErrEmptySlice is returned when an empty slice is passed to a CRUD method that requires a non-empty slice.
var ErrFileNotFound = errors.New("file with given parameters not found")
ErrFileNotFound occurs if a user asks to download a file with a file ID that isn't found in the files collection.
var ErrInvalidIndexValue = errors.New("invalid index value")
ErrInvalidIndexValue is returned if an index is created with a keys document that has a value that is not a number or string.
var ErrMissingChunk = errors.New("EOF missing one or more chunks")
ErrMissingChunk indicates that the number of chunks read from the server is less than expected. This error is specific to GridFS operations.
var ErrMissingGridFSChunkSize = errors.New("files collection document does not contain a 'chunkSize' field")
ErrMissingGridFSChunkSize occurs when downloading a file if the files collection document is missing the "chunkSize" field.
var ErrMultipleIndexDrop = errors.New("multiple indexes would be dropped")
ErrMultipleIndexDrop is returned if multiple indexes would be dropped from a call to IndexView.DropOne.
var ErrNilDocument = errors.New("document is nil")
ErrNilDocument is returned when a nil document is passed to a CRUD method.
var ErrNilValue = errors.New("value is nil")
ErrNilValue is returned when a nil value is passed to a CRUD method.
var ErrNoDocuments = errors.New("mongo: no documents in result")
ErrNoDocuments is returned by SingleResult methods when the operation that created the SingleResult did not return any documents.
var ErrNonStringIndexName = errors.New("index name must be a string")
ErrNonStringIndexName is returned if an index is created with a name that is not a string.
var ErrNotSlice = errors.New("must provide a non-empty slice")
ErrNotSlice is returned when a type other than slice is passed to InsertMany.
var ErrStreamClosed = errors.New("stream is closed or aborted")
ErrStreamClosed is an error returned if an operation is attempted on a closed/aborted stream.
var ErrWrongClient = errors.New("session was not created by this client")
ErrWrongClient is returned when a user attempts to pass in a session created by a different client than the method call is using.
var ErrWrongSize = errors.New("chunk size does not match expected size")
ErrWrongSize is used when the chunk retrieved from the server does not have the expected size. This error is specific to GridFS operations.
Functions ¶
func BatchCursorFromCursor
deprecated
func BatchCursorFromCursor(c *Cursor) *driver.BatchCursor
BatchCursorFromCursor returns a driver.BatchCursor for the given Cursor. If there is no underlying driver.BatchCursor, nil is returned.
Deprecated: This is an unstable function because the driver.BatchCursor type exists in the "x" package. Neither this function nor the driver.BatchCursor type should be used by applications and may be changed or removed in any release.
func IsDuplicateKeyError ¶
IsDuplicateKeyError returns true if err is a duplicate key error. For BulkWriteExceptions, IsDuplicateKeyError returns true if at least one of the errors is a duplicate key error.
func IsNetworkError ¶
IsNetworkError returns true if err is a network error
func IsTimeout ¶
IsTimeout returns true if err was caused by a timeout. For error chains, IsTimeout returns true if any error in the chain was caused by a timeout.
func NewSessionContext ¶
NewSessionContext returns a Context that holds the given Session. If the Context already contains a Session, that Session will be replaced with the one provided.
The returned Context can be used with Collection methods like Collection.InsertOne or Collection.Find to run operations in a Session.
Example ¶
package main import ( "context" "fmt" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" ) func main() { var client *mongo.Client // Create a new Session and SessionContext. sess, err := client.StartSession() if err != nil { panic(err) } defer sess.EndSession(context.TODO()) ctx := mongo.NewSessionContext(context.TODO(), sess) // Start a transaction and use the context.Context as the Context // parameter for InsertOne and FindOne so both operations are run in the // transaction. if err = sess.StartTransaction(); err != nil { panic(err) } coll := client.Database("db").Collection("coll") res, err := coll.InsertOne(ctx, bson.D{{"x", 1}}) if err != nil { // Abort the transaction after an error. Use context.Background() to // ensure that the abort can complete successfully even if the context // passed to NewSessionContext is changed to have a timeout. _ = sess.AbortTransaction(context.Background()) panic(err) } var result bson.M err = coll.FindOne( ctx, bson.D{{"_id", res.InsertedID}}, ).Decode(&result) if err != nil { // Abort the transaction after an error. Use context.Background() to // ensure that the abort can complete successfully even if the context // passed to NewSessionContext is changed to have a timeout. _ = sess.AbortTransaction(context.Background()) panic(err) } fmt.Printf("result: %v\n", result) // Commit the transaction so the inserted document will be stored. Use // context.Background() to ensure that the commit can complete successfully // even if the context passed to NewSessionContext is changed to have a // timeout. if err = sess.CommitTransaction(context.Background()); err != nil { panic(err) } }
Output:
func WithSession ¶
WithSession creates a new session context from the ctx and sess parameters and uses it to call the fn callback.
WithSession is safe to call from multiple goroutines concurrently. However, the context passed to the WithSession callback function is not safe for concurrent use by multiple goroutines.
If the ctx parameter already contains a Session, that Session will be replaced with the one provided.
Any error returned by the fn callback will be returned without any modifications.
Example ¶
package main import ( "context" "fmt" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" "go.mongodb.org/mongo-driver/v2/mongo/readconcern" ) func main() { // Assume client is configured with write concern majority and read // preference primary. var client *mongo.Client // Specify the DefaultReadConcern option so any transactions started through // the session will have read concern majority. // The DefaultReadPreference and DefaultWriteConcern options aren't // specified so they will be inheritied from client and be set to primary // and majority, respectively. txnOpts := options.Transaction().SetReadConcern(readconcern.Majority()) opts := options.Session().SetDefaultTransactionOptions(txnOpts) sess, err := client.StartSession(opts) if err != nil { log.Panic(err) } defer sess.EndSession(context.TODO()) // Call WithSession to start a transaction within the new session. err = mongo.WithSession( context.TODO(), sess, func(ctx context.Context) error { // Use the context.Context as the Context parameter for // InsertOne and FindOne so both operations are run under the new // Session. if err := sess.StartTransaction(); err != nil { return err } coll := client.Database("db").Collection("coll") res, err := coll.InsertOne(ctx, bson.D{{"x", 1}}) if err != nil { // Abort the transaction after an error. Use // context.Background() to ensure that the abort can complete // successfully even if the context passed to mongo.WithSession // is changed to have a timeout. _ = sess.AbortTransaction(context.Background()) return err } var result bson.M err = coll.FindOne( ctx, bson.D{{"_id", res.InsertedID}}, ).Decode(result) if err != nil { // Abort the transaction after an error. Use // context.Background() to ensure that the abort can complete // successfully even if the context passed to mongo.WithSession // is changed to have a timeout. _ = sess.AbortTransaction(context.Background()) return err } fmt.Println(result) // Use context.Background() to ensure that the commit can complete // successfully even if the context passed to mongo.WithSession is // changed to have a timeout. return sess.CommitTransaction(context.Background()) }) if err != nil { log.Panic(err) } }
Output:
Types ¶
type BulkWriteError ¶
type BulkWriteError struct { WriteError // The WriteError that occurred. Request WriteModel // The WriteModel that caused this error. }
BulkWriteError is an error that occurred during execution of one operation in a BulkWrite. This error type is only returned as part of a BulkWriteException.
func (BulkWriteError) Error ¶
func (bwe BulkWriteError) Error() string
Error implements the error interface.
type BulkWriteException ¶
type BulkWriteException struct { // The write concern error that occurred, or nil if there was none. WriteConcernError *WriteConcernError // The write errors that occurred during operation execution. WriteErrors []BulkWriteError // The categories to which the exception belongs. Labels []string }
BulkWriteException is the error type returned by BulkWrite and InsertMany operations.
func (BulkWriteException) Error ¶
func (bwe BulkWriteException) Error() string
Error implements the error interface.
func (BulkWriteException) HasErrorCode ¶
func (bwe BulkWriteException) HasErrorCode(code int) bool
HasErrorCode returns true if any of the errors have the specified code.
func (BulkWriteException) HasErrorCodeWithMessage ¶
func (bwe BulkWriteException) HasErrorCodeWithMessage(code int, message string) bool
HasErrorCodeWithMessage returns true if any of the contained errors have the specified code and message.
func (BulkWriteException) HasErrorLabel ¶
func (bwe BulkWriteException) HasErrorLabel(label string) bool
HasErrorLabel returns true if the error contains the specified label.
func (BulkWriteException) HasErrorMessage ¶
func (bwe BulkWriteException) HasErrorMessage(message string) bool
HasErrorMessage returns true if the error contains the specified message.
type BulkWriteResult ¶
type BulkWriteResult struct { // The number of documents inserted. InsertedCount int64 // The number of documents matched by filters in update and replace operations. MatchedCount int64 // The number of documents modified by update and replace operations. ModifiedCount int64 // The number of documents deleted. DeletedCount int64 // The number of documents upserted by update and replace operations. UpsertedCount int64 // A map of operation index to the _id of each upserted document. UpsertedIDs map[int64]interface{} // Operation performed with an acknowledged write. Values for other fields may // not be deterministic if the write operation was unacknowledged. Acknowledged bool }
BulkWriteResult is the result type returned by a BulkWrite operation.
type ChangeStream ¶
type ChangeStream struct { // Current is the BSON bytes of the current event. This property is only valid until the next call to Next or // TryNext. If continued access is required, a copy must be made. Current bson.Raw // contains filtered or unexported fields }
ChangeStream is used to iterate over a stream of events. Each event can be decoded into a Go type via the Decode method or accessed as raw BSON via the Current field. This type is not goroutine safe and must not be used concurrently by multiple goroutines. For more information about change streams, see https://www.mongodb.com/docs/manual/changeStreams/.
func (*ChangeStream) Close ¶
func (cs *ChangeStream) Close(ctx context.Context) error
Close closes this change stream and the underlying cursor. Next and TryNext must not be called after Close has been called. Close is idempotent. After the first call, any subsequent calls will not change the state.
func (*ChangeStream) Decode ¶
func (cs *ChangeStream) Decode(val interface{}) error
Decode will unmarshal the current event document into val and return any errors from the unmarshalling process without any modification. If val is nil or is a typed nil, an error will be returned.
func (*ChangeStream) Err ¶
func (cs *ChangeStream) Err() error
Err returns the last error seen by the change stream, or nil if no errors has occurred.
func (*ChangeStream) ID ¶
func (cs *ChangeStream) ID() int64
ID returns the ID for this change stream, or 0 if the cursor has been closed or exhausted.
func (*ChangeStream) Next ¶
func (cs *ChangeStream) Next(ctx context.Context) bool
Next gets the next event for this change stream. It returns true if there were no errors and the next event document is available.
Next blocks until an event is available, an error occurs, or ctx expires. If ctx expires, the error will be set to ctx.Err(). In an error case, Next will return false.
If Next returns false, subsequent calls will also return false.
Example ¶
package main import ( "context" "fmt" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" ) func main() { var stream *mongo.ChangeStream defer stream.Close(context.TODO()) // Iterate the change stream and print out each event. // Because the Next call blocks until an event is available, another way to // iterate the change stream is to call Next in a goroutine and pass in a // context that can be cancelled to abort the call. for stream.Next(context.TODO()) { // A new event variable should be declared for each event. var event bson.M if err := stream.Decode(&event); err != nil { log.Panic(err) } fmt.Println(event) } if err := stream.Err(); err != nil { log.Panic(err) } }
Output:
func (*ChangeStream) RemainingBatchLength ¶
func (cs *ChangeStream) RemainingBatchLength() int
RemainingBatchLength returns the number of documents left in the current batch. If this returns zero, the subsequent call to Next or TryNext will do a network request to fetch the next batch.
func (*ChangeStream) ResumeToken ¶
func (cs *ChangeStream) ResumeToken() bson.Raw
ResumeToken returns the last cached resume token for this change stream, or nil if a resume token has not been stored.
Example ¶
package main import ( "context" "fmt" "log" "sync" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { var client *mongo.Client // Assume stream was created via client.Watch() var stream *mongo.ChangeStream cancelCtx, cancel := context.WithCancel(context.TODO()) defer cancel() var wg sync.WaitGroup wg.Add(1) // Run a goroutine to process events. go func() { for stream.Next(cancelCtx) { fmt.Println(stream.Current) } wg.Done() }() // Assume client needs to be disconnected. Cancel the context being used by // the goroutine to abort any in-progres Next calls and wait for the // goroutine to exit. cancel() wg.Wait() // Before disconnecting the client, store the last seen resume token for the // change stream. resumeToken := stream.ResumeToken() _ = client.Disconnect(context.TODO()) // Once a new client is created, the change stream can be re-created. // Specify resumeToken as the ResumeAfter option so only events that // occurred after resumeToken will be returned. var newClient *mongo.Client opts := options.ChangeStream().SetResumeAfter(resumeToken) newStream, err := newClient.Watch(context.TODO(), mongo.Pipeline{}, opts) if err != nil { log.Panic(err) } defer newStream.Close(context.TODO()) }
Output:
func (*ChangeStream) SetBatchSize ¶
func (cs *ChangeStream) SetBatchSize(size int32)
SetBatchSize sets the number of documents to fetch from the database with each iteration of the ChangeStream's "Next" or "TryNext" method. This setting only affects subsequent document batches fetched from the database.
func (*ChangeStream) TryNext ¶
func (cs *ChangeStream) TryNext(ctx context.Context) bool
TryNext attempts to get the next event for this change stream. It returns true if there were no errors and the next event document is available.
TryNext returns false if the change stream is closed by the server, an error occurs when getting changes from the server, the next change is not yet available, or ctx expires.
If ctx expires, the error will be set to ctx.Err(). Users can either call TryNext again or close the existing change stream and create a new one. It is suggested to close and re-create the stream with ah higher timeout if the timeout occurs before any events have been received, which is a signal that the server is timing out before it can finish processing the existing oplog.
If TryNext returns false and an error occurred or the change stream was closed (i.e. cs.Err() != nil || cs.ID() == 0), subsequent attempts will also return false. Otherwise, it is safe to call TryNext again until a change is available.
This method requires driver version >= 1.2.0.
Example ¶
package main import ( "context" "fmt" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" ) func main() { var stream *mongo.ChangeStream defer stream.Close(context.TODO()) // Iterate the change stream and print out each event until the change // stream is closed by the server or there is an error getting the next // event. for { if stream.TryNext(context.TODO()) { // A new event variable should be declared for each event. var event bson.M if err := stream.Decode(&event); err != nil { log.Panic(err) } fmt.Println(event) continue } // If TryNext returns false, the next change is not yet available, the // change stream was closed by the server, or an error occurred. TryNext // should only be called again for the empty batch case. if err := stream.Err(); err != nil { log.Panic(err) } if stream.ID() == 0 { break } } }
Output:
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a handle representing a pool of connections to a MongoDB deployment. It is safe for concurrent use by multiple goroutines.
The Client type opens and closes connections automatically and maintains a pool of idle connections. For connection pool configuration options, see documentation for the ClientOptions type in the mongo/options package.
Example ¶
package main import ( "context" "fmt" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { // Create a Client and execute a ListDatabases operation. client, err := mongo.Connect( options.Client().ApplyURI("mongodb://localhost:27017")) if err != nil { log.Panic(err) } defer func() { if err = client.Disconnect(context.TODO()); err != nil { log.Panic(err) } }() collection := client.Database("db").Collection("coll") result, err := collection.InsertOne(context.TODO(), bson.D{{"x", 1}}) if err != nil { log.Panic(err) } fmt.Printf("inserted ID: %v\n", result.InsertedID) }
Output:
func Connect ¶
Connect creates a new Client and then initializes it using the Connect method.
When creating an options.ClientOptions, the order the methods are called matters. Later Set* methods will overwrite the values from previous Set* method invocations. This includes the ApplyURI method. This allows callers to determine the order of precedence for option application. For instance, if ApplyURI is called before SetAuth, the Credential from SetAuth will overwrite the values from the connection string. If ApplyURI is called after SetAuth, then its values will overwrite those from SetAuth.
The opts parameter is processed using options.MergeClientOptions, which will overwrite entire option fields of previous options, there is no partial overwriting. For example, if Username is set in the Auth field for the first option, and Password is set for the second but with no Username, after the merge the Username field will be empty.
The NewClient function does not do any I/O and returns an error if the given options are invalid. The Client.Connect method starts background goroutines to monitor the state of the deployment and does not do any I/O in the main goroutine to prevent the main goroutine from blocking. Therefore, it will not error if the deployment is down.
The Client.Ping method can be used to verify that the deployment is successfully connected and the Client was correctly configured.
Example (AWS) ¶
package main import ( "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { // Configure a Client with authentication using the MONGODB-AWS // authentication mechanism. Credentials for this mechanism can come from // one of four sources: // // 1. AWS IAM credentials (an access key ID and a secret access key) // // 2. Temporary AWS IAM credentials // (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html) // obtained from an AWS Security Token Service (STS) Assume Role request // (https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) // // 3. AWS Lambda environment variables // (https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html#configuration-envvars-runtime) // // 4. Temporary AWS IAM credentials assigned to an EC2 instance or ECS task // (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html) // The order in which the driver searches for credentials is: // // 1. Credentials passed through the URI // 2. Environment variables // 3. ECS endpoint if and only if AWS_CONTAINER_CREDENTIALS_RELATIVE_URI is // set // 4. EC2 endpoint // // The following examples set the appropriate credentials via the // ClientOptions.SetAuth method. All of these credentials can be specified // via the ClientOptions.ApplyURI method as well. If using ApplyURI, both // the username and password must be URL encoded (see net.URL.QueryEscape()) // AWS IAM Credentials // Applications can authenticate using AWS IAM credentials by providing a // valid access key ID and secret access key pair as the username and // password, respectively. var accessKeyID, secretAccessKey string awsCredential := options.Credential{ AuthMechanism: "MONGODB-AWS", Username: accessKeyID, Password: secretAccessKey, } awsIAMClient, err := mongo.Connect( options.Client().SetAuth(awsCredential)) if err != nil { panic(err) } _ = awsIAMClient // AssumeRole // Applications can authenticate using temporary credentials returned from // an assume role request. These temporary credentials consist of an access // key ID, a secret access key, and a security token. var sessionToken string assumeRoleCredential := options.Credential{ AuthMechanism: "MONGODB-AWS", Username: accessKeyID, Password: secretAccessKey, AuthMechanismProperties: map[string]string{ "AWS_SESSION_TOKEN": sessionToken, }, } assumeRoleClient, err := mongo.Connect( options.Client().SetAuth(assumeRoleCredential)) if err != nil { panic(err) } _ = assumeRoleClient // AWS Lambda (Environment Variables) // When the username and password are not provided and the MONGODB-AWS // mechanism is set, the client will fallback to using the environment // variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN // for the access key ID, secret access key, and session token, // respectively. These environment variables must not be URL encoded. // $ export AWS_ACCESS_KEY_ID=<accessKeyID> // $ export AWS_SECRET_ACCESS_KEY=<secretAccessKey> // $ export AWS_SESSION_TOKEN=<sessionToken> envVariablesCredential := options.Credential{ AuthMechanism: "MONGODB-AWS", } envVariablesClient, err := mongo.Connect( options.Client().SetAuth(envVariablesCredential)) if err != nil { panic(err) } _ = envVariablesClient // ECS Container or EC2 Instance // Applications can authenticate from an ECS container or EC2 instance via // temporary credentials assigned to the machine. If using an ECS container, // the "AWS_CONTAINER_CREDENTIALS_RELATIVE_URI" environment variable must be // set to a non-empty value. The driver will query the ECS or EC2 endpoint // to obtain the relevant credentials. ecCredential := options.Credential{ AuthMechanism: "MONGODB-AWS", } ecClient, err := mongo.Connect(options.Client().SetAuth(ecCredential)) if err != nil { panic(err) } _ = ecClient }
Output:
Example (BSONOptions) ¶
package main import ( "context" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { // Configure a client that customizes the BSON marshal and unmarshal // behavior. // Specify BSON options that cause the driver to fallback to "json" // struct tags if "bson" struct tags are missing, marshal nil Go maps as // empty BSON documents, and marshals nil Go slices as empty BSON // arrays. bsonOpts := &options.BSONOptions{ UseJSONStructTags: true, NilMapAsEmpty: true, NilSliceAsEmpty: true, } clientOpts := options.Client(). ApplyURI("mongodb://localhost:27017"). SetBSONOptions(bsonOpts) client, err := mongo.Connect(clientOpts) if err != nil { panic(err) } defer func() { if err := client.Disconnect(context.TODO()); err != nil { panic(err) } }() coll := client.Database("db").Collection("coll") // Define a struct that contains a map and a slice and uses "json" struct // tags to specify field names. type myDocument struct { MyMap map[string]interface{} `json:"a"` MySlice []string `json:"b"` } // Insert an instance of the struct with all empty fields. Expect the // resulting BSON document to have a structure like {"a": {}, "b": []} _, err = coll.InsertOne(context.TODO(), myDocument{}) if err != nil { panic(err) } }
Output:
Example (Direct) ¶
package main import ( "log" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { // Create a direct connection to a host. The driver will send all requests // to that host and will not automatically discover other hosts in the // deployment. clientOpts := options.Client().ApplyURI( "mongodb://localhost:27017/?connect=direct") client, err := mongo.Connect(clientOpts) if err != nil { log.Panic(err) } _ = client }
Output:
Example (Kerberos) ¶
package main import ( "log" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { // Configure a Client with GSSAPI/SSPI authentication (https://www.mongodb.com/docs/manual/core/kerberos/). // MongoDB Enterprise supports proxy authentication through a Kerberos // service. Using Kerberos authentication requires the "gssapi" build tag // and cgo support during compilation. The default service name for Kerberos // is "mongodb". This can be configured via the AuthMechanismProperties // field in the options.Credential struct or the authMechanismProperties URI // parameter. // For Linux, the libkrb5 library is required. // Users can authenticate in one of two ways: // 1. Use an explicit password. In this case, a password must be specified // in the URI or the options.Credential struct and no further setup is // required. // 2. Store authentication keys in keytab files. To do this, the kinit // binary should be used to initialize a credential cache for authenticating // the user principal. In this example, the invocation would be // "kinit drivers@KERBEROS.EXAMPLE.COM". // To configure auth via a URI instead of a Credential, use // "mongodb://drivers%40KERBEROS.EXAMPLE.COM@mongo-server.example.com:27017/?authMechanism=GSSAPI". credential := options.Credential{ AuthMechanism: "GSSAPI", Username: "drivers@KERBEROS.EXAMPLE.COM", } uri := "mongo-server.example.com:27017" clientOpts := options.Client().ApplyURI(uri).SetAuth(credential) client, err := mongo.Connect(clientOpts) if err != nil { log.Panic(err) } _ = client }
Output:
Example (OIDC) ¶
package main import ( "context" "os" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { // The `MONGODB-OIDC authentication mechanism` is available in MongoDB 7.0+ // on Linux platforms. // // The MONGODB-OIDC mechanism authenticates using an OpenID Connect (OIDC) // access token. The driver supports OIDC for workload identity, defined as // an identity you assign to a software workload (such as an application, // service, script, or container) to authenticate and access other services // and resources. // // The driver also supports OIDC for workforce identity for a more secure // flow with a human in the loop. // Credentials can be configured through the MongoDB URI or as arguments in // the options.ClientOptions struct that is passed into the mongo.Connect // function. // Built-in Support // The driver has built-in support for Azure IMDS and GCP // IMDS environments. Other environments are supported with `Custom // Callbacks`. // Azure IMDS // For an application running on an Azure VM or otherwise using the `Azure // Internal Metadata Service`, you can use the built-in support for Azure, // where "<client_id>" below is the client id of the Azure managed identity, // and ``<audience>`` is the url-encoded ``audience`` `configured on your // MongoDB deployment`. { uri := os.Getenv("MONGODB_URI") props := map[string]string{ "ENVIRONMENT": "azure", "TOKEN_RESOURCE": "<audience>", } opts := options.Client().ApplyURI(uri) opts.SetAuth( options.Credential{ Username: "<client_id>", AuthMechanism: "MONGODB-OIDC", AuthMechanismProperties: props, }, ) c, err := mongo.Connect(opts) if err != nil { panic(err) } defer func() { _ = c.Disconnect(context.TODO()) }() _, err = c.Database("test"). Collection("test"). InsertOne(context.TODO(), bson.D{}) if err != nil { panic(err) } } // If the application is running on an Azure VM and only one managed // identity is associated with the VM, "username" can be omitted. // GCP IMDS // For an application running on an GCP VM or otherwise using the `GCP // Internal Metadata Service`_, you can use the built-in support for GCP, // where "<audience>" below is the url-encoded "audience" `configured on // your MongoDB deployment`. { uri := os.Getenv("MONGODB_URI") props := map[string]string{ "ENVIRONMENT": "gcp", "TOKEN_RESOURCE": "<audience>", } opts := options.Client().ApplyURI(uri) opts.SetAuth( options.Credential{ AuthMechanism: "MONGODB-OIDC", AuthMechanismProperties: props, }, ) c, err := mongo.Connect(opts) if err != nil { panic(err) } defer func() { _ = c.Disconnect(context.TODO()) }() _, err = c.Database("test"). Collection("test"). InsertOne(context.TODO(), bson.D{}) if err != nil { panic(err) } } // Custom Callbacks // For environments that are not directly supported by the driver, you can // use options.OIDCCallback. Some examples are given below. // AWS EKS // For an EKS Cluster with a configured `IAM OIDC provider`, the token can // be read from a path given by the "AWS_WEB_IDENTITY_TOKEN_FILE" // environment variable. { eksCallback := func(_ context.Context, _ *options.OIDCArgs) (*options.OIDCCredential, error) { accessToken, err := os.ReadFile( os.Getenv("AWS_WEB_IDENTITY_TOKEN_FILE")) if err != nil { return nil, err } return &options.OIDCCredential{ AccessToken: string(accessToken), }, nil } uri := os.Getenv("MONGODB_URI") opts := options.Client().ApplyURI(uri) opts.SetAuth( options.Credential{ AuthMechanism: "MONGODB-OIDC", OIDCMachineCallback: eksCallback, }, ) c, err := mongo.Connect(opts) if err != nil { panic(err) } defer func() { _ = c.Disconnect(context.TODO()) }() _, err = c.Database("test"). Collection("test"). InsertOne(context.TODO(), bson.D{}) if err != nil { panic(err) } } // Other Azure Environments // For applications running on Azure Functions, App Service Environment // (ASE), or Azure Kubernetes Service (AKS), you can use the `azidentity // package` // (https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity) to // fetch the credentials. In each case, the OIDCCallback function should // return the AccessToken from the azidentity package. // GCP GKE // For a Google Kubernetes Engine cluster with a `configured service // account`, the token can be read from the standard service account token // file location. { gkeCallback := func(_ context.Context, _ *options.OIDCArgs) (*options.OIDCCredential, error) { accessToken, err := os.ReadFile( "/var/run/secrets/kubernetes.io/serviceaccount/token") if err != nil { return nil, err } return &options.OIDCCredential{ AccessToken: string(accessToken), }, nil } uri := os.Getenv("MONGODB_URI") props := map[string]string{ "ENVIRONMENT": "gcp", "TOKEN_RESOURCE": "<audience>", } opts := options.Client().ApplyURI(uri) opts.SetAuth( options.Credential{ AuthMechanism: "MONGODB-OIDC", AuthMechanismProperties: props, OIDCMachineCallback: gkeCallback, }, ) c, err := mongo.Connect(opts) if err != nil { panic(err) } defer func() { _ = c.Disconnect(context.TODO()) }() _, err = c.Database("test"). Collection("test"). InsertOne(context.TODO(), bson.D{}) if err != nil { panic(err) } } // For workforce identity, the Client must be configured with the // OIDCHumanCallback rather than the OIDCMachineCallback. The // OIDCHumanCallback is used by the driver in a process that is two step. In // the first step, the driver retrieves the Identity Provider (IDP) // Information (IDPInfo) for the passed username. The OIDCHumanCallback then // needs to negotiate with the IDP in order to obtain an AccessToken, // possible RefreshToken, any timeouts, and return them, similar to the // OIDCMachineCallbacks seen above. See // https://docs.hidglobal.com/dev/auth-service/integration/openid-authentication-flows.html // for more information on various OIDC authentication flows. { humanCallback := func(ctx context.Context, opts *options.OIDCArgs) (*options.OIDCCredential, error) { // idpInfo passed from the driver by asking the MongoDB server for // the info configured for the username idpInfo := opts.IDPInfo // negotiateWithIDP must work with the IdP to obtain an access // token. In many cases this will involve opening a webbrowser or // providing a URL on the command line to a human-in-the-loop who // can give permissions to the IdP. accessToken, err := negotiateWithIDP(ctx, idpInfo.Issuer) if err != nil { return nil, err } return &options.OIDCCredential{ AccessToken: accessToken, }, nil } uri := os.Getenv("MONGODB_URI") props := map[string]string{ "ENVIRONMENT": "gcp", "TOKEN_RESOURCE": "<audience>", } opts := options.Client().ApplyURI(uri) opts.SetAuth( options.Credential{ AuthMechanism: "MONGODB-OIDC", AuthMechanismProperties: props, OIDCHumanCallback: humanCallback, }, ) c, err := mongo.Connect(opts) if err != nil { panic(err) } defer func() { _ = c.Disconnect(context.TODO()) }() _, err = c.Database("test"). Collection("test"). InsertOne(context.TODO(), bson.D{}) if err != nil { panic(err) } } // * MONGODB-OIDC authentication mechanism: // https://www.mongodb.com/docs/manual/core/security-oidc/ // * OIDC Identity Provider Configuration: // https://www.mongodb.com/docs/manual/reference/parameters/#mongodb-parameter-param.oidcIdentityProviders // * Azure Internal Metadata Service: // https://learn.microsoft.com/en-us/azure/virtual-machines/instance-metadata-service // * GCP Internal Metadata Service: // https://cloud.google.com/compute/docs/metadata/querying-metadata // * IAM OIDC provider: // https://docs.aws.amazon.com/eks/latest/userguide/enable-iam-roles-for-service-accounts.html // * azure-identity package: // https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity // * configured service account: // https://cloud.google.com/kubernetes-engine/docs/how-to/service-accounts } func negotiateWithIDP(_ context.Context, _ string) (string, error) { return "", nil }
Output:
Example (PLAIN) ¶
package main import ( "log" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { // Configure a Client with LDAP authentication // (https://www.mongodb.com/docs/manual/core/authentication-mechanisms-enterprise/#security-auth-ldap). // MongoDB Enterprise supports proxy authentication through an LDAP service // that can be used through the PLAIN authentication mechanism. // This auth mechanism sends the password in plaintext and therefore should // only be used with TLS connections. // To configure auth via a URI instead of a Credential, use // "mongodb://ldap-user:ldap-pwd@localhost:27017/?authMechanism=PLAIN". credential := options.Credential{ AuthMechanism: "PLAIN", Username: "ldap-user", Password: "ldap-pwd", } clientOpts := options.Client().ApplyURI("mongodb://localhost:27017"). SetAuth(credential) client, err := mongo.Connect(clientOpts) if err != nil { log.Panic(err) } _ = client }
Output:
Example (Ping) ¶
package main import ( "context" "log" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" "go.mongodb.org/mongo-driver/v2/mongo/readpref" ) func main() { // Create a Client to a MongoDB server and use Ping to verify that the // server is running. clientOpts := options.Client().ApplyURI("mongodb://localhost:27017") client, err := mongo.Connect(clientOpts) if err != nil { log.Panic(err) } defer func() { if err = client.Disconnect(context.TODO()); err != nil { log.Panic(err) } }() // Call Ping to verify that the deployment is up and the Client was // configured successfully. As mentioned in the Ping documentation, this // reduces application resiliency as the server may be temporarily // unavailable when Ping is called. if err = client.Ping(context.TODO(), readpref.Primary()); err != nil { log.Panic(err) } }
Output:
Example (ReplicaSet) ¶
package main import ( "log" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { // Create and connect a Client to a replica set deployment. // Given this URI, the Go driver will first communicate with localhost:27017 // and use the response to discover any other members in the replica set. // The URI in this example specifies multiple members of the replica set to // increase resiliency as one of the members may be down when the // application is started. clientOpts := options.Client().ApplyURI( "mongodb://localhost:27017,localhost:27018/?replicaSet=replset") client, err := mongo.Connect(clientOpts) if err != nil { log.Panic(err) } _ = client }
Output:
Example (SCRAM) ¶
package main import ( "log" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { // Configure a Client with SCRAM authentication // (https://www.mongodb.com/docs/manual/core/security-scram/). // The default authentication database for SCRAM is "admin". This can be // configured via the authSource query parameter in the URI or the // AuthSource field in the options.Credential struct. SCRAM is the default // auth mechanism so specifying a mechanism is not required. // To configure auth via URI instead of a Credential, use // "mongodb://user:password@localhost:27017". credential := options.Credential{ Username: "user", Password: "password", } clientOpts := options.Client().ApplyURI("mongodb://localhost:27017"). SetAuth(credential) client, err := mongo.Connect(clientOpts) if err != nil { log.Panic(err) } _ = client }
Output:
Example (SRV) ¶
package main import ( "log" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { // Create and connect a Client using an SRV record. // SRV records allow administrators to configure a single domain to return a // list of host names. The driver will resolve SRV records prefixed with // "_mongodb_tcp" and use the returned host names to build its view of the // deployment. // See https://www.mongodb.com/docs/manual/reference/connection-string/ for more // information about SRV. Full support for SRV records with sharded clusters // requires driver version 1.1.0 or higher. clientOpts := options.Client().ApplyURI("mongodb+srv://mongodb.example.com") client, err := mongo.Connect(clientOpts) if err != nil { log.Panic(err) } _ = client }
Output:
Example (Sharded) ¶
package main import ( "log" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { // Create and connect a Client to a sharded deployment. // The URI for a sharded deployment should specify the mongos servers that // the application wants to send messages to. clientOpts := options.Client().ApplyURI( "mongodb://localhost:27017,localhost:27018") client, err := mongo.Connect(clientOpts) if err != nil { log.Panic(err) } _ = client }
Output:
Example (StableAPI) ¶
package main import ( "context" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { // Configure a Client with stable API. // // Stable API is a new feature in MongoDB 5.0 that allows user-selectable // API versions, subsets of MongoDB server semantics, to be declared on a // Client. During communication with a server, Clients with a declared API // version will force that server to behave in a manner compatible with the // API version. Declaring an API version on your Client can be used to // ensure consistent responses from a server, providing long term API // stability for an application. // // The declared API version is applied to all commands run through the // Client, including those sent through the generic RunCommand helper. // Specifying stable API options in the command document AND declaring // an API version on the Client is not supported and will lead to undefined // behavior. To run any command with a different API version or without // declaring one, create a separate Client that declares the appropriate API // version. // ServerAPIOptions must be declared with an API version. ServerAPIVersion1 // is a constant equal to "1". serverAPI := options.ServerAPI(options.ServerAPIVersion1) serverAPIClient, err := mongo.Connect( options.Client().SetServerAPIOptions(serverAPI)) if err != nil { panic(err) } _ = serverAPIClient // ServerAPIOptions can be declared with a Strict option. Declaring a strict // API version will cause the MongoDB server to reject all commands that are // not part of the declared API version. This includes command options and // aggregation pipeline stages. For example, the following Distinct call // would fail because the distinct command is not part of API version 1: serverAPIStrict := options.ServerAPI(options.ServerAPIVersion1). SetStrict(true) serverAPIStrictClient, err := mongo.Connect( options.Client().SetServerAPIOptions(serverAPIStrict)) if err != nil { panic(err) } coll := serverAPIStrictClient.Database("db").Collection("coll") // Fails with error: (APIStrictError) Provided apiStrict:true, but the // command distinct is not in API Version 1 err = coll.Distinct(context.TODO(), "distinct", bson.D{}).Err() log.Println(err) // ServerAPIOptions can be declared with a DeprecationErrors option. // DeprecationErrors can be used to enable command failures when using // functionality that is deprecated in the declared API version. Note that // at the time of this writing, no deprecations in API version 1 exist. serverAPIDeprecation := options.ServerAPI(options.ServerAPIVersion1). SetDeprecationErrors(true) serverAPIDeprecationClient, err := mongo.Connect( options.Client().SetServerAPIOptions(serverAPIDeprecation)) if err != nil { panic(err) } _ = serverAPIDeprecationClient }
Output:
Example (X509) ¶
package main import ( "fmt" "log" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { // Configure a Client with X509 authentication // (https://www.mongodb.com/docs/manual/core/security-x.509/). // X509 can be configured with different sets of options in the connection // string: // 1. tlsCAFile (or SslCertificateAuthorityFile): Path to the file with // either a single or bundle of certificate authorities to be considered // trusted when making a TLS connection. // 2. tlsCertificateKeyFile (or SslClientCertificateKeyFile): Path to the // client certificate file or the client private key file. In the case that // both are needed, the files should be concatenated. // The SetAuth client option should also be used. The username field is // optional. If it is not specified, it will be extracted from the // certificate key file. The AuthSource is required to be $external. caFilePath := "path/to/cafile" certificateKeyFilePath := "path/to/client-certificate" // To configure auth via a URI instead of a Credential, append // "&authMechanism=MONGODB-X509" to the URI. uri := "mongodb://host:port/?tlsCAFile=%s&tlsCertificateKeyFile=%s" uri = fmt.Sprintf(uri, caFilePath, certificateKeyFilePath) credential := options.Credential{ AuthMechanism: "MONGODB-X509", } clientOpts := options.Client().ApplyURI(uri).SetAuth(credential) client, err := mongo.Connect(clientOpts) if err != nil { log.Panic(err) } _ = client }
Output:
func (*Client) Database ¶
Database returns a handle for a database with the given name configured with the given DatabaseOptions.
func (*Client) Disconnect ¶
Disconnect closes sockets to the topology referenced by this Client. It will shut down any monitoring goroutines, close the idle connection pool, and will wait until all the in use connections have been returned to the connection pool and closed before returning. If the context expires via cancellation, deadline, or timeout before the in use connections have returned, the in use connections will be closed, resulting in the failure of any in flight read or write operations. If this method returns with no errors, all connections associated with this Client have been closed.
func (*Client) ListDatabaseNames ¶
func (c *Client) ListDatabaseNames(ctx context.Context, filter interface{}, opts ...options.Lister[options.ListDatabasesOptions]) ([]string, error)
ListDatabaseNames executes a listDatabases command and returns a slice containing the names of all of the databases on the server.
The filter parameter must be a document containing query operators and can be used to select which databases are included in the result. It cannot be nil. An empty document (e.g. bson.D{}) should be used to include all databases.
The opts parameter can be used to specify options for this operation (see the options.ListDatabasesOptions documentation.)
For more information about the command, see https://www.mongodb.com/docs/manual/reference/command/listDatabases/.
Example ¶
package main import ( "context" "fmt" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" ) func main() { var client *mongo.Client // Use a filter to only select non-empty databases. result, err := client.ListDatabaseNames( context.TODO(), bson.D{{"empty", false}}) if err != nil { log.Panic(err) } for _, db := range result { fmt.Println(db) } }
Output:
func (*Client) ListDatabases ¶
func (c *Client) ListDatabases(ctx context.Context, filter interface{}, opts ...options.Lister[options.ListDatabasesOptions]) (ListDatabasesResult, error)
ListDatabases executes a listDatabases command and returns the result.
The filter parameter must be a document containing query operators and can be used to select which databases are included in the result. It cannot be nil. An empty document (e.g. bson.D{}) should be used to include all databases.
The opts parameter can be used to specify options for this operation (see the options.ListDatabasesOptions documentation).
For more information about the command, see https://www.mongodb.com/docs/manual/reference/command/listDatabases/.
func (*Client) NumberSessionsInProgress ¶
NumberSessionsInProgress returns the number of sessions that have been started for this client but have not been closed (i.e. EndSession has not been called).
func (*Client) Ping ¶
Ping sends a ping command to verify that the client can connect to the deployment.
The rp parameter is used to determine which server is selected for the operation. If it is nil, the client's read preference is used.
If the server is down, Ping will try to select a server until the client's server selection timeout expires. This can be configured through the ClientOptions.SetServerSelectionTimeout option when creating a new Client. After the timeout expires, a server selection error is returned.
Using Ping reduces application resilience because applications starting up will error if the server is temporarily unavailable or is failing over (e.g. during autoscaling due to a load spike).
func (*Client) StartSession ¶
StartSession starts a new session configured with the given options.
StartSession does not actually communicate with the server and will not error if the client is disconnected.
StartSession is safe to call from multiple goroutines concurrently. However, Sessions returned by StartSession are not safe for concurrent use by multiple goroutines.
If the DefaultReadConcern, DefaultWriteConcern, or DefaultReadPreference options are not set, the client's read concern, write concern, or read preference will be used, respectively.
Example (WithTransaction) ¶
package main import ( "context" "fmt" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" "go.mongodb.org/mongo-driver/v2/mongo/readconcern" "go.mongodb.org/mongo-driver/v2/mongo/readpref" ) func main() { // Assume client is configured with write concern majority and read // preference primary. var client *mongo.Client // Specify the DefaultReadConcern option so any transactions started through // the session will have read concern majority. // The DefaultReadPreference and DefaultWriteConcern options aren't // specified so they will be inheritied from client and be set to primary // and majority, respectively. txnOpts := options.Transaction().SetReadConcern(readconcern.Majority()) opts := options.Session().SetDefaultTransactionOptions(txnOpts) sess, err := client.StartSession(opts) if err != nil { log.Panic(err) } defer sess.EndSession(context.TODO()) // Specify the ReadPreference option to set the read preference to primary // preferred for this transaction. txnOpts.SetReadPreference(readpref.PrimaryPreferred()) result, err := sess.WithTransaction( context.TODO(), func(ctx context.Context) (interface{}, error) { // Use the context.Context as the Context parameter for // InsertOne and FindOne so both operations are run in the same // transaction. coll := client.Database("db").Collection("coll") res, err := coll.InsertOne(ctx, bson.D{{"x", 1}}) if err != nil { return nil, err } var result bson.M err = coll.FindOne( ctx, bson.D{{"_id", res.InsertedID}}, ).Decode(result) if err != nil { return nil, err } return result, err }, txnOpts) if err != nil { log.Panic(err) } fmt.Printf("result: %v\n", result) }
Output:
func (*Client) UseSession ¶
UseSession creates a new Session and uses it to create a new session context, which is used to call the fn callback. After the callback returns, the created Session is ended, meaning that any in-progress transactions started by fn will be aborted even if fn returns an error.
UseSession is safe to call from multiple goroutines concurrently. However, the context passed to the UseSession callback function is not safe for concurrent use by multiple goroutines.
If the ctx parameter already contains a Session, that Session will be replaced with the newly created one.
Any error returned by the fn callback will be returned without any modifications.
func (*Client) UseSessionWithOptions ¶
func (c *Client) UseSessionWithOptions( ctx context.Context, opts *options.SessionOptionsBuilder, fn func(context.Context) error, ) error
UseSessionWithOptions operates like UseSession but uses the given SessionOptions to create the Session.
UseSessionWithOptions is safe to call from multiple goroutines concurrently. However, the context passed to the UseSessionWithOptions callback function is not safe for concurrent use by multiple goroutines.
Example ¶
package main import ( "context" "fmt" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" "go.mongodb.org/mongo-driver/v2/mongo/readconcern" ) func main() { var client *mongo.Client // Specify the DefaultReadConcern option so any transactions started through // the session will have read concern majority. // The DefaultReadPreference and DefaultWriteConcern options aren't // specified so they will be inheritied from client and be set to primary // and majority, respectively. txnOpts := options.Transaction().SetReadConcern(readconcern.Majority()) opts := options.Session().SetDefaultTransactionOptions(txnOpts) err := client.UseSessionWithOptions( context.TODO(), opts, func(ctx context.Context) error { sess := mongo.SessionFromContext(ctx) // Use the context.Context as the Context parameter for // InsertOne and FindOne so both operations are run under the new // Session. if err := sess.StartTransaction(); err != nil { return err } coll := client.Database("db").Collection("coll") res, err := coll.InsertOne(ctx, bson.D{{"x", 1}}) if err != nil { // Abort the transaction after an error. Use // context.Background() to ensure that the abort can complete // successfully even if the context passed to mongo.WithSession // is changed to have a timeout. _ = sess.AbortTransaction(context.Background()) return err } var result bson.M err = coll.FindOne( ctx, bson.D{{"_id", res.InsertedID}}, ).Decode(result) if err != nil { // Abort the transaction after an error. Use // context.Background() to ensure that the abort can complete // successfully even if the context passed to mongo.WithSession // is changed to have a timeout. _ = sess.AbortTransaction(context.Background()) return err } fmt.Println(result) // Use context.Background() to ensure that the commit can complete // successfully even if the context passed to mongo.WithSession is // changed to have a timeout. return sess.CommitTransaction(context.Background()) }) if err != nil { log.Panic(err) } }
Output:
func (*Client) Watch ¶
func (c *Client) Watch(ctx context.Context, pipeline interface{}, opts ...options.Lister[options.ChangeStreamOptions]) (*ChangeStream, error)
Watch returns a change stream for all changes on the deployment. See https://www.mongodb.com/docs/manual/changeStreams/ for more information about change streams.
The client must be configured with read concern majority or no read concern for a change stream to be created successfully.
The pipeline parameter must be an array of documents, each representing a pipeline stage. The pipeline cannot be nil or empty. The stage documents must all be non-nil. See https://www.mongodb.com/docs/manual/changeStreams/ for a list of pipeline stages that can be used with change streams. For a pipeline of bson.D documents, the mongo.Pipeline{} type can be used.
The opts parameter can be used to specify options for change stream creation (see the options.ChangeStreamOptions documentation).
Example ¶
package main import ( "context" "fmt" "log" "time" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { var client *mongo.Client // Specify a pipeline that will only match "insert" events. // Specify the MaxAwaitTimeOption to have each attempt wait two seconds for // new documents. matchStage := bson.D{{"$match", bson.D{{"operationType", "insert"}}}} opts := options.ChangeStream().SetMaxAwaitTime(2 * time.Second) changeStream, err := client.Watch( context.TODO(), mongo.Pipeline{matchStage}, opts) if err != nil { log.Panic(err) } // Print out all change stream events in the order they're received. // See the mongo.ChangeStream documentation for more examples of using // change streams. for changeStream.Next(context.TODO()) { fmt.Println(changeStream.Current) } }
Output:
type ClientEncryption ¶
type ClientEncryption struct {
// contains filtered or unexported fields
}
ClientEncryption is used to create data keys and explicitly encrypt and decrypt BSON values.
func NewClientEncryption ¶
func NewClientEncryption(keyVaultClient *Client, opts ...options.Lister[options.ClientEncryptionOptions]) (*ClientEncryption, error)
NewClientEncryption creates a new ClientEncryption instance configured with the given options.
func (*ClientEncryption) AddKeyAltName ¶
func (ce *ClientEncryption) AddKeyAltName(ctx context.Context, id bson.Binary, keyAltName string) *SingleResult
AddKeyAltName adds a keyAltName to the keyAltNames array of the key document in the key vault collection with the given UUID (BSON binary subtype 0x04). Returns the previous version of the key document.
func (*ClientEncryption) Close ¶
func (ce *ClientEncryption) Close(ctx context.Context) error
Close cleans up any resources associated with the ClientEncryption instance. This includes disconnecting the key-vault Client instance.
func (*ClientEncryption) CreateDataKey ¶
func (ce *ClientEncryption) CreateDataKey( ctx context.Context, kmsProvider string, opts ...options.Lister[options.DataKeyOptions], ) (bson.Binary, error)
CreateDataKey creates a new key document and inserts into the key vault collection. Returns the _id of the created document as a UUID (BSON binary subtype 0x04).
func (*ClientEncryption) CreateEncryptedCollection ¶
func (ce *ClientEncryption) CreateEncryptedCollection(ctx context.Context, db *Database, coll string, createOpts options.Lister[options.CreateCollectionOptions], kmsProvider string, masterKey interface{}) (*Collection, bson.M, error)
CreateEncryptedCollection creates a new collection for Queryable Encryption with the help of automatic generation of new encryption data keys for null keyIds. It returns the created collection and the encrypted fields document used to create it.
func (*ClientEncryption) Decrypt ¶
Decrypt decrypts an encrypted value (BSON binary of subtype 6) and returns the original BSON value.
func (*ClientEncryption) DeleteKey ¶
func (ce *ClientEncryption) DeleteKey(ctx context.Context, id bson.Binary) (*DeleteResult, error)
DeleteKey removes the key document with the given UUID (BSON binary subtype 0x04) from the key vault collection. Returns the result of the internal deleteOne() operation on the key vault collection.
func (*ClientEncryption) Encrypt ¶
func (ce *ClientEncryption) Encrypt( ctx context.Context, val bson.RawValue, opts ...options.Lister[options.EncryptOptions], ) (bson.Binary, error)
Encrypt encrypts a BSON value with the given key and algorithm. Returns an encrypted value (BSON binary of subtype 6).
func (*ClientEncryption) EncryptExpression ¶
func (ce *ClientEncryption) EncryptExpression(ctx context.Context, expr interface{}, result interface{}, opts ...options.Lister[options.EncryptOptions]) error
EncryptExpression encrypts an expression to query a range index. On success, `result` is populated with the resulting BSON document. `expr` is expected to be a BSON document of one of the following forms: 1. A Match Expression of this form: {$and: [{<field>: {$gt: <value1>}}, {<field>: {$lt: <value2> }}]} 2. An Aggregate Expression of this form: {$and: [{$gt: [<fieldpath>, <value1>]}, {$lt: [<fieldpath>, <value2>]}] $gt may also be $gte. $lt may also be $lte. Only supported for queryType "range"
func (*ClientEncryption) GetKey ¶
func (ce *ClientEncryption) GetKey(ctx context.Context, id bson.Binary) *SingleResult
GetKey finds a single key document with the given UUID (BSON binary subtype 0x04). Returns the result of the internal find() operation on the key vault collection.
func (*ClientEncryption) GetKeyByAltName ¶
func (ce *ClientEncryption) GetKeyByAltName(ctx context.Context, keyAltName string) *SingleResult
GetKeyByAltName returns a key document in the key vault collection with the given keyAltName.
func (*ClientEncryption) GetKeys ¶
func (ce *ClientEncryption) GetKeys(ctx context.Context) (*Cursor, error)
GetKeys finds all documents in the key vault collection. Returns the result of the internal find() operation on the key vault collection.
func (*ClientEncryption) RemoveKeyAltName ¶
func (ce *ClientEncryption) RemoveKeyAltName(ctx context.Context, id bson.Binary, keyAltName string) *SingleResult
RemoveKeyAltName removes a keyAltName from the keyAltNames array of the key document in the key vault collection with the given UUID (BSON binary subtype 0x04). Returns the previous version of the key document.
func (*ClientEncryption) RewrapManyDataKey ¶
func (ce *ClientEncryption) RewrapManyDataKey( ctx context.Context, filter interface{}, opts ...options.Lister[options.RewrapManyDataKeyOptions], ) (*RewrapManyDataKeyResult, error)
RewrapManyDataKey decrypts and encrypts all matching data keys with a possibly new masterKey value. For all matching documents, this method will overwrite the "masterKey", "updateDate", and "keyMaterial". On error, some matching data keys may have been rewrapped. libmongocrypt 1.5.2 is required. An error is returned if the detected version of libmongocrypt is less than 1.5.2.
type Collection ¶
type Collection struct {
// contains filtered or unexported fields
}
Collection is a handle to a MongoDB collection. It is safe for concurrent use by multiple goroutines.
func (*Collection) Aggregate ¶
func (coll *Collection) Aggregate( ctx context.Context, pipeline interface{}, opts ...options.Lister[options.AggregateOptions], ) (*Cursor, error)
Aggregate executes an aggregate command against the collection and returns a cursor over the resulting documents.
The pipeline parameter must be an array of documents, each representing an aggregation stage. The pipeline cannot be nil but can be empty. The stage documents must all be non-nil. For a pipeline of bson.D documents, the mongo.Pipeline type can be used. See https://www.mongodb.com/docs/manual/reference/operator/aggregation-pipeline/#db-collection-aggregate-stages for a list of valid stages in aggregations.
The opts parameter can be used to specify options for the operation (see the options.AggregateOptions documentation.)
For more information about the command, see https://www.mongodb.com/docs/manual/reference/command/aggregate/.
Example ¶
package main import ( "context" "fmt" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { var coll *mongo.Collection // Specify a pipeline that will return the number of times each name appears // in the collection. // Specify the MaxTime option to limit the amount of time the operation can // run on the server. groupStage := bson.D{ {"$group", bson.D{ {"_id", "$name"}, {"numTimes", bson.D{ {"$sum", 1}, }}, }}, } opts := options.Aggregate() cursor, err := coll.Aggregate( context.TODO(), mongo.Pipeline{groupStage}, opts) if err != nil { log.Panic(err) } // Get a list of all returned documents and print them out. // See the mongo.Cursor documentation for more examples of using cursors. var results []bson.M if err = cursor.All(context.TODO(), &results); err != nil { log.Panic(err) } for _, result := range results { fmt.Printf( "name %v appears %v times\n", result["_id"], result["numTimes"]) } }
Output:
func (*Collection) BulkWrite ¶
func (coll *Collection) BulkWrite(ctx context.Context, models []WriteModel, opts ...options.Lister[options.BulkWriteOptions]) (*BulkWriteResult, error)
BulkWrite performs a bulk write operation (https://www.mongodb.com/docs/manual/core/bulk-write-operations/).
The models parameter must be a slice of operations to be executed in this bulk write. It cannot be nil or empty. All of the models must be non-nil. See the mongo.WriteModel documentation for a list of valid model types and examples of how they should be used.
The opts parameter can be used to specify options for the operation (see the options.BulkWriteOptions documentation.)
Example ¶
package main import ( "context" "fmt" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { var coll *mongo.Collection var firstID, secondID bson.ObjectID // Update the "email" field for two users. // For each update, specify the Upsert option to insert a new document if a // document matching the filter isn't found. // Set the Ordered option to false to allow both operations to happen even // if one of them errors. firstUpdate := bson.D{ {"$set", bson.D{ {"email", "firstEmail@example.com"}, }}, } secondUpdate := bson.D{ {"$set", bson.D{ {"email", "secondEmail@example.com"}, }}, } models := []mongo.WriteModel{ mongo.NewUpdateOneModel().SetFilter(bson.D{{"_id", firstID}}). SetUpdate(firstUpdate).SetUpsert(true), mongo.NewUpdateOneModel().SetFilter(bson.D{{"_id", secondID}}). SetUpdate(secondUpdate).SetUpsert(true), } opts := options.BulkWrite().SetOrdered(false) res, err := coll.BulkWrite(context.TODO(), models, opts) if err != nil { log.Panic(err) } fmt.Printf( "inserted %v and deleted %v documents\n", res.InsertedCount, res.DeletedCount) }
Output:
func (*Collection) Clone ¶
func (coll *Collection) Clone(opts ...options.Lister[options.CollectionOptions]) *Collection
Clone creates a copy of the Collection configured with the given CollectionOptions. The specified options are merged with the existing options on the collection, with the specified options taking precedence.
func (*Collection) CountDocuments ¶
func (coll *Collection) CountDocuments(ctx context.Context, filter interface{}, opts ...options.Lister[options.CountOptions]) (int64, error)
CountDocuments returns the number of documents in the collection. For a fast count of the documents in the collection, see the EstimatedDocumentCount method.
The filter parameter must be a document and can be used to select which documents contribute to the count. It cannot be nil. An empty document (e.g. bson.D{}) should be used to count all documents in the collection. This will result in a full collection scan.
The opts parameter can be used to specify options for the operation (see the options.CountOptions documentation).
Example ¶
package main import ( "context" "fmt" "log" "time" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" ) func main() { var coll *mongo.Collection // Specify a timeout to limit the amount of time the operation can run on // the server. ctx, cancel := context.WithTimeout(context.TODO(), time.Second) defer cancel() // Count the number of times the name "Bob" appears in the collection. count, err := coll.CountDocuments(ctx, bson.D{{"name", "Bob"}}, nil) if err != nil { log.Panic(err) } fmt.Printf("name Bob appears in %v documents", count) }
Output:
func (*Collection) Database ¶
func (coll *Collection) Database() *Database
Database returns the Database that was used to create the Collection.
func (*Collection) DeleteMany ¶
func (coll *Collection) DeleteMany( ctx context.Context, filter interface{}, opts ...options.Lister[options.DeleteOptions], ) (*DeleteResult, error)
DeleteMany executes a delete command to delete documents from the collection.
The filter parameter must be a document containing query operators and can be used to select the documents to be deleted. It cannot be nil. An empty document (e.g. bson.D{}) should be used to delete all documents in the collection. If the filter does not match any documents, the operation will succeed and a DeleteResult with a DeletedCount of 0 will be returned.
The opts parameter can be used to specify options for the operation (see the options.DeleteOptions documentation).
For more information about the command, see https://www.mongodb.com/docs/manual/reference/command/delete/.
Example ¶
package main import ( "context" "fmt" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { var coll *mongo.Collection // Delete all documents in which the "name" field is "Bob" or "bob". // Specify the Collation option to provide a collation that will ignore case // for string comparisons. opts := options.Delete().SetCollation(&options.Collation{ Locale: "en_US", Strength: 1, CaseLevel: false, }) res, err := coll.DeleteMany(context.TODO(), bson.D{{"name", "bob"}}, opts) if err != nil { log.Panic(err) } fmt.Printf("deleted %v documents\n", res.DeletedCount) }
Output:
func (*Collection) DeleteOne ¶
func (coll *Collection) DeleteOne( ctx context.Context, filter interface{}, opts ...options.Lister[options.DeleteOptions], ) (*DeleteResult, error)
DeleteOne executes a delete command to delete at most one document from the collection.
The filter parameter must be a document containing query operators and can be used to select the document to be deleted. It cannot be nil. If the filter does not match any documents, the operation will succeed and a DeleteResult with a DeletedCount of 0 will be returned. If the filter matches multiple documents, one will be selected from the matched set.
The opts parameter can be used to specify options for the operation (see the options.DeleteOptions documentation).
For more information about the command, see https://www.mongodb.com/docs/manual/reference/command/delete/.
Example ¶
package main import ( "context" "fmt" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { var coll *mongo.Collection // Delete at most one document in which the "name" field is "Bob" or "bob". // Specify the SetCollation option to provide a collation that will ignore // case for string comparisons. opts := options.Delete().SetCollation(&options.Collation{ Locale: "en_US", Strength: 1, CaseLevel: false, }) res, err := coll.DeleteOne(context.TODO(), bson.D{{"name", "bob"}}, opts) if err != nil { log.Panic(err) } fmt.Printf("deleted %v documents\n", res.DeletedCount) }
Output:
func (*Collection) Distinct ¶
func (coll *Collection) Distinct( ctx context.Context, fieldName string, filter interface{}, opts ...options.Lister[options.DistinctOptions], ) *DistinctResult
Distinct executes a distinct command to find the unique values for a specified field in the collection.
The fieldName parameter specifies the field name for which distinct values should be returned.
The filter parameter must be a document containing query operators and can be used to select which documents are considered. It cannot be nil. An empty document (e.g. bson.D{}) should be used to select all documents.
The opts parameter can be used to specify options for the operation (see the options.DistinctOptions documentation).
For more information about the command, see https://www.mongodb.com/docs/manual/reference/command/distinct/.
Example ¶
package main import ( "context" "fmt" "log" "time" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" ) func main() { var coll *mongo.Collection // Specify a timeout to limit the amount of time the operation can run on // the server. ctx, cancel := context.WithTimeout(context.TODO(), time.Second) defer cancel() // Find all unique values for the "name" field for documents in which the // "age" field is greater than 25. filter := bson.D{{"age", bson.D{{"$gt", 25}}}} res := coll.Distinct(ctx, "name", filter) if err := res.Err(); err != nil { log.Panic(err) } values, err := res.Raw() if err != nil { log.Panic(err) } for _, value := range values { fmt.Println(value) } }
Output:
func (*Collection) Drop ¶
func (coll *Collection) Drop(ctx context.Context, opts ...options.Lister[options.DropCollectionOptions]) error
Drop drops the collection on the server. This method ignores "namespace not found" errors so it is safe to drop a collection that does not exist on the server.
func (*Collection) EstimatedDocumentCount ¶
func (coll *Collection) EstimatedDocumentCount( ctx context.Context, opts ...options.Lister[options.EstimatedDocumentCountOptions], ) (int64, error)
EstimatedDocumentCount executes a count command and returns an estimate of the number of documents in the collection using collection metadata.
The opts parameter can be used to specify options for the operation (see the options.EstimatedDocumentCountOptions documentation).
For more information about the command, see https://www.mongodb.com/docs/manual/reference/command/count/.
Example ¶
package main import ( "context" "fmt" "log" "time" "go.mongodb.org/mongo-driver/v2/mongo" ) func main() { var coll *mongo.Collection // Specify a timeout to limit the amount of time the operation can run on // the server. ctx, cancel := context.WithTimeout(context.TODO(), time.Second) defer cancel() // Get and print an estimated of the number of documents in the collection. count, err := coll.EstimatedDocumentCount(ctx, nil) if err != nil { log.Panic(err) } fmt.Printf("estimated document count: %v", count) }
Output:
func (*Collection) Find ¶
func (coll *Collection) Find(ctx context.Context, filter interface{}, opts ...options.Lister[options.FindOptions]) (*Cursor, error)
Find executes a find command and returns a Cursor over the matching documents in the collection.
The filter parameter must be a document containing query operators and can be used to select which documents are included in the result. It cannot be nil. An empty document (e.g. bson.D{}) should be used to include all documents.
The opts parameter can be used to specify options for the operation (see the options.FindOptions documentation).
For more information about the command, see https://www.mongodb.com/docs/manual/reference/command/find/.
Example ¶
package main import ( "context" "fmt" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { var coll *mongo.Collection // Find all documents in which the "name" field is "Bob". // Specify the Sort option to sort the returned documents by age in // ascending order. opts := options.Find().SetSort(bson.D{{"age", 1}}) cursor, err := coll.Find(context.TODO(), bson.D{{"name", "Bob"}}, opts) if err != nil { log.Panic(err) } // Get a list of all returned documents and print them out. // See the mongo.Cursor documentation for more examples of using cursors. var results []bson.M if err = cursor.All(context.TODO(), &results); err != nil { log.Panic(err) } for _, result := range results { fmt.Println(result) } }
Output:
Example (PrimitiveRegex) ¶
package main import ( "context" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { ctx := context.TODO() clientOptions := options.Client().ApplyURI("mongodb://localhost:27017") // Connect to a mongodb server. client, err := mongo.Connect(clientOptions) if err != nil { panic(err) } defer func() { _ = client.Disconnect(ctx) }() type Pet struct { Type string `bson:"type"` Name string `bson:"name"` } // Create a slice of documents to insert. We will lookup a subset of // these documents using regex. toInsert := []interface{}{ Pet{Type: "cat", Name: "Mo"}, Pet{Type: "dog", Name: "Loki"}, } coll := client.Database("test").Collection("test") if _, err := coll.InsertMany(ctx, toInsert); err != nil { panic(err) } // Create a filter to find a document with key "name" and any value that // starts with letter "m". Use the "i" option to indicate // case-insensitivity. filter := bson.D{{"name", bson.Regex{Pattern: "^m", Options: "i"}}} _, err = coll.Find(ctx, filter) if err != nil { panic(err) } }
Output:
Example (Regex) ¶
package main import ( "context" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { ctx := context.TODO() clientOptions := options.Client().ApplyURI("mongodb://localhost:27017") // Connect to a mongodb server. client, err := mongo.Connect(clientOptions) if err != nil { panic(err) } defer func() { _ = client.Disconnect(ctx) }() type Pet struct { Type string `bson:"type"` Name string `bson:"name"` } // Create a slice of documents to insert. We will lookup a subset of // these documents using regex. toInsert := []interface{}{ Pet{Type: "cat", Name: "Mo"}, Pet{Type: "dog", Name: "Loki"}, } coll := client.Database("test").Collection("test") if _, err := coll.InsertMany(ctx, toInsert); err != nil { panic(err) } // Create a filter to find a document with key "name" and any value that // starts with letter "m". Use the "i" option to indicate // case-insensitivity. filter := bson.D{{"name", bson.D{{"$regex", "^m"}, {"$options", "i"}}}} _, err = coll.Find(ctx, filter) if err != nil { panic(err) } }
Output:
func (*Collection) FindOne ¶
func (coll *Collection) FindOne(ctx context.Context, filter interface{}, opts ...options.Lister[options.FindOneOptions]) *SingleResult
FindOne executes a find command and returns a SingleResult for one document in the collection.
The filter parameter must be a document containing query operators and can be used to select the document to be returned. It cannot be nil. If the filter does not match any documents, a SingleResult with an error set to ErrNoDocuments will be returned. If the filter matches multiple documents, one will be selected from the matched set.
The opts parameter can be used to specify options for this operation (see the options.FindOneOptions documentation).
For more information about the command, see https://www.mongodb.com/docs/manual/reference/command/find/.
Example ¶
package main import ( "context" "errors" "fmt" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { var coll *mongo.Collection var id bson.ObjectID // Find the document for which the _id field matches id. // Specify the Sort option to sort the documents by age. // The first document in the sorted order will be returned. opts := options.FindOne().SetSort(bson.D{{"age", 1}}) var result bson.M err := coll.FindOne( context.TODO(), bson.D{{"_id", id}}, opts, ).Decode(&result) if err != nil { // ErrNoDocuments means that the filter did not match any documents in // the collection. if errors.Is(err, mongo.ErrNoDocuments) { return } log.Panic(err) } fmt.Printf("found document %v", result) }
Output:
func (*Collection) FindOneAndDelete ¶
func (coll *Collection) FindOneAndDelete( ctx context.Context, filter interface{}, opts ...options.Lister[options.FindOneAndDeleteOptions]) *SingleResult
FindOneAndDelete executes a findAndModify command to delete at most one document in the collection. and returns the document as it appeared before deletion.
The filter parameter must be a document containing query operators and can be used to select the document to be deleted. It cannot be nil. If the filter does not match any documents, a SingleResult with an error set to ErrNoDocuments wil be returned. If the filter matches multiple documents, one will be selected from the matched set.
The opts parameter can be used to specify options for the operation (see the options.FindOneAndDeleteOptions documentation).
For more information about the command, see https://www.mongodb.com/docs/manual/reference/command/findAndModify/.
Example ¶
package main import ( "context" "errors" "fmt" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { var coll *mongo.Collection var id bson.ObjectID // Find and delete the document for which the _id field matches id. // Specify the Projection option to only include the name and age fields in // the returned document. opts := options.FindOneAndDelete(). SetProjection(bson.D{{"name", 1}, {"age", 1}}) var deletedDocument bson.M err := coll.FindOneAndDelete( context.TODO(), bson.D{{"_id", id}}, opts, ).Decode(&deletedDocument) if err != nil { // ErrNoDocuments means that the filter did not match any documents in // the collection. if errors.Is(err, mongo.ErrNoDocuments) { return } log.Panic(err) } fmt.Printf("deleted document %v", deletedDocument) }
Output:
func (*Collection) FindOneAndReplace ¶
func (coll *Collection) FindOneAndReplace( ctx context.Context, filter interface{}, replacement interface{}, opts ...options.Lister[options.FindOneAndReplaceOptions], ) *SingleResult
FindOneAndReplace executes a findAndModify command to replace at most one document in the collection and returns the document as it appeared before replacement.
The filter parameter must be a document containing query operators and can be used to select the document to be replaced. It cannot be nil. If the filter does not match any documents, a SingleResult with an error set to ErrNoDocuments wil be returned. If the filter matches multiple documents, one will be selected from the matched set.
The replacement parameter must be a document that will be used to replace the selected document. It cannot be nil and cannot contain any update operators (https://www.mongodb.com/docs/manual/reference/operator/update/).
The opts parameter can be used to specify options for the operation (see the options.FindOneAndReplaceOptions documentation).
For more information about the command, see https://www.mongodb.com/docs/manual/reference/command/findAndModify/.
Example ¶
package main import ( "context" "errors" "fmt" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { var coll *mongo.Collection var id bson.ObjectID // Find the document for which the _id field matches id and add a field // called "location". // Specify the Upsert option to insert a new document if a document matching // the filter isn't found. opts := options.FindOneAndReplace().SetUpsert(true) filter := bson.D{{"_id", id}} replacement := bson.D{{"location", "NYC"}} var replacedDocument bson.M err := coll.FindOneAndReplace( context.TODO(), filter, replacement, opts, ).Decode(&replacedDocument) if err != nil { // ErrNoDocuments means that the filter did not match any documents in // the collection. if errors.Is(err, mongo.ErrNoDocuments) { return } log.Panic(err) } fmt.Printf("replaced document %v", replacedDocument) }
Output:
func (*Collection) FindOneAndUpdate ¶
func (coll *Collection) FindOneAndUpdate( ctx context.Context, filter interface{}, update interface{}, opts ...options.Lister[options.FindOneAndUpdateOptions]) *SingleResult
FindOneAndUpdate executes a findAndModify command to update at most one document in the collection and returns the document as it appeared before updating.
The filter parameter must be a document containing query operators and can be used to select the document to be updated. It cannot be nil. If the filter does not match any documents, a SingleResult with an error set to ErrNoDocuments wil be returned. If the filter matches multiple documents, one will be selected from the matched set.
The update parameter must be a document containing update operators (https://www.mongodb.com/docs/manual/reference/operator/update/) and can be used to specify the modifications to be made to the selected document. It cannot be nil or empty.
The opts parameter can be used to specify options for the operation (see the options.FindOneAndUpdateOptions documentation).
For more information about the command, see https://www.mongodb.com/docs/manual/reference/command/findAndModify/.
Example ¶
package main import ( "context" "errors" "fmt" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { var coll *mongo.Collection var id bson.ObjectID // Find the document for which the _id field matches id and set the email to // "newemail@example.com". // Specify the Upsert option to insert a new document if a document matching // the filter isn't found. opts := options.FindOneAndUpdate().SetUpsert(true) filter := bson.D{{"_id", id}} update := bson.D{{"$set", bson.D{{"email", "newemail@example.com"}}}} var updatedDocument bson.M err := coll.FindOneAndUpdate( context.TODO(), filter, update, opts, ).Decode(&updatedDocument) if err != nil { // ErrNoDocuments means that the filter did not match any documents in // the collection. if errors.Is(err, mongo.ErrNoDocuments) { return } log.Panic(err) } fmt.Printf("updated document %v", updatedDocument) }
Output:
func (*Collection) Indexes ¶
func (coll *Collection) Indexes() IndexView
Indexes returns an IndexView instance that can be used to perform operations on the indexes for the collection.
func (*Collection) InsertMany ¶
func (coll *Collection) InsertMany( ctx context.Context, documents interface{}, opts ...options.Lister[options.InsertManyOptions], ) (*InsertManyResult, error)
InsertMany executes an insert command to insert multiple documents into the collection. If write errors occur during the operation (e.g. duplicate key error), this method returns a BulkWriteException error.
The documents parameter must be a slice of documents to insert. The slice cannot be nil or empty. The elements must all be non-nil. For any document that does not have an _id field when transformed into BSON, one will be added automatically to the marshalled document. The original document will not be modified. The _id values for the inserted documents can be retrieved from the InsertedIDs field of the returned InsertManyResult.
The opts parameter can be used to specify options for the operation (see the options.InsertManyOptions documentation.)
For more information about the command, see https://www.mongodb.com/docs/manual/reference/command/insert/.
Example ¶
package main import ( "context" "fmt" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { var coll *mongo.Collection // Insert documents {name: "Alice"} and {name: "Bob"}. // Set the Ordered option to false to allow both operations to happen even // if one of them errors. docs := []interface{}{ bson.D{{"name", "Alice"}}, bson.D{{"name", "Bob"}}, } opts := options.InsertMany().SetOrdered(false) res, err := coll.InsertMany(context.TODO(), docs, opts) if err != nil { log.Panic(err) } fmt.Printf("inserted documents with IDs %v\n", res.InsertedIDs) }
Output:
func (*Collection) InsertOne ¶
func (coll *Collection) InsertOne(ctx context.Context, document interface{}, opts ...options.Lister[options.InsertOneOptions]) (*InsertOneResult, error)
InsertOne executes an insert command to insert a single document into the collection.
The document parameter must be the document to be inserted. It cannot be nil. If the document does not have an _id field when transformed into BSON, one will be added automatically to the marshalled document. The original document will not be modified. The _id can be retrieved from the InsertedID field of the returned InsertOneResult.
The opts parameter can be used to specify options for the operation (see the options.InsertOneOptions documentation.)
For more information about the command, see https://www.mongodb.com/docs/manual/reference/command/insert/.
Example ¶
package main import ( "context" "fmt" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" ) func main() { var coll *mongo.Collection // Insert the document {name: "Alice"}. res, err := coll.InsertOne(context.TODO(), bson.D{{"name", "Alice"}}) if err != nil { log.Panic(err) } fmt.Printf("inserted document with ID %v\n", res.InsertedID) }
Output:
func (*Collection) Name ¶
func (coll *Collection) Name() string
Name returns the name of the collection.
func (*Collection) ReplaceOne ¶
func (coll *Collection) ReplaceOne( ctx context.Context, filter interface{}, replacement interface{}, opts ...options.Lister[options.ReplaceOptions], ) (*UpdateResult, error)
ReplaceOne executes an update command to replace at most one document in the collection.
The filter parameter must be a document containing query operators and can be used to select the document to be replaced. It cannot be nil. If the filter does not match any documents, the operation will succeed and an UpdateResult with a MatchedCount of 0 will be returned. If the filter matches multiple documents, one will be selected from the matched set and MatchedCount will equal 1.
The replacement parameter must be a document that will be used to replace the selected document. It cannot be nil and cannot contain any update operators (https://www.mongodb.com/docs/manual/reference/operator/update/).
The opts parameter can be used to specify options for the operation (see the options.ReplaceOptions documentation).
For more information about the command, see https://www.mongodb.com/docs/manual/reference/command/update/.
Example ¶
package main import ( "context" "fmt" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { var coll *mongo.Collection var id bson.ObjectID // Find the document for which the _id field matches id and add a field // called "location". // Specify the Upsert option to insert a new document if a document matching // the filter isn't found. opts := options.Replace().SetUpsert(true) filter := bson.D{{"_id", id}} replacement := bson.D{{"location", "NYC"}} result, err := coll.ReplaceOne(context.TODO(), filter, replacement, opts) if err != nil { log.Panic(err) } if result.MatchedCount != 0 { fmt.Println("matched and replaced an existing document") return } if result.UpsertedCount != 0 { fmt.Printf("inserted a new document with ID %v\n", result.UpsertedID) } }
Output:
func (*Collection) SearchIndexes ¶
func (coll *Collection) SearchIndexes() SearchIndexView
SearchIndexes returns a SearchIndexView instance that can be used to perform operations on the search indexes for the collection.
func (*Collection) UpdateByID ¶
func (coll *Collection) UpdateByID( ctx context.Context, id interface{}, update interface{}, opts ...options.Lister[options.UpdateOptions], ) (*UpdateResult, error)
UpdateByID executes an update command to update the document whose _id value matches the provided ID in the collection. This is equivalent to running UpdateOne(ctx, bson.D{{"_id", id}}, update, opts...).
The id parameter is the _id of the document to be updated. It cannot be nil. If the ID does not match any documents, the operation will succeed and an UpdateResult with a MatchedCount of 0 will be returned.
The update parameter must be a document containing update operators (https://www.mongodb.com/docs/manual/reference/operator/update/) and can be used to specify the modifications to be made to the selected document. It cannot be nil or empty.
The opts parameter can be used to specify options for the operation (see the options.UpdateOptions documentation).
For more information about the command, see https://www.mongodb.com/docs/manual/reference/command/update/.
func (*Collection) UpdateMany ¶
func (coll *Collection) UpdateMany( ctx context.Context, filter interface{}, update interface{}, opts ...options.Lister[options.UpdateOptions], ) (*UpdateResult, error)
UpdateMany executes an update command to update documents in the collection.
The filter parameter must be a document containing query operators and can be used to select the documents to be updated. It cannot be nil. If the filter does not match any documents, the operation will succeed and an UpdateResult with a MatchedCount of 0 will be returned.
The update parameter must be a document containing update operators (https://www.mongodb.com/docs/manual/reference/operator/update/) and can be used to specify the modifications to be made to the selected documents. It cannot be nil or empty.
The opts parameter can be used to specify options for the operation (see the options.UpdateOptions documentation).
For more information about the command, see https://www.mongodb.com/docs/manual/reference/command/update/.
Example ¶
package main import ( "context" "fmt" "log" "time" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" ) func main() { var coll *mongo.Collection // Increment the age for all users whose birthday is today. today := time.Now().Format("01-01-1970") filter := bson.D{{"birthday", today}} update := bson.D{{"$inc", bson.D{{"age", 1}}}} result, err := coll.UpdateMany(context.TODO(), filter, update) if err != nil { log.Panic(err) } if result.MatchedCount != 0 { fmt.Println("matched and replaced an existing document") return } }
Output:
func (*Collection) UpdateOne ¶
func (coll *Collection) UpdateOne( ctx context.Context, filter interface{}, update interface{}, opts ...options.Lister[options.UpdateOptions], ) (*UpdateResult, error)
UpdateOne executes an update command to update at most one document in the collection.
The filter parameter must be a document containing query operators and can be used to select the document to be updated. It cannot be nil. If the filter does not match any documents, the operation will succeed and an UpdateResult with a MatchedCount of 0 will be returned. If the filter matches multiple documents, one will be selected from the matched set and MatchedCount will equal 1.
The update parameter must be a document containing update operators (https://www.mongodb.com/docs/manual/reference/operator/update/) and can be used to specify the modifications to be made to the selected document. It cannot be nil or empty.
The opts parameter can be used to specify options for the operation (see the options.UpdateOptions documentation).
For more information about the command, see https://www.mongodb.com/docs/manual/reference/command/update/.
Example ¶
package main import ( "context" "fmt" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { var coll *mongo.Collection var id bson.ObjectID // Find the document for which the _id field matches id and set the email to // "newemail@example.com". // Specify the Upsert option to insert a new document if a document matching // the filter isn't found. opts := options.Update().SetUpsert(true) filter := bson.D{{"_id", id}} update := bson.D{{"$set", bson.D{{"email", "newemail@example.com"}}}} result, err := coll.UpdateOne(context.TODO(), filter, update, opts) if err != nil { log.Panic(err) } if result.MatchedCount != 0 { fmt.Println("matched and replaced an existing document") return } if result.UpsertedCount != 0 { fmt.Printf("inserted a new document with ID %v\n", result.UpsertedID) } }
Output:
func (*Collection) Watch ¶
func (coll *Collection) Watch(ctx context.Context, pipeline interface{}, opts ...options.Lister[options.ChangeStreamOptions]) (*ChangeStream, error)
Watch returns a change stream for all changes on the corresponding collection. See https://www.mongodb.com/docs/manual/changeStreams/ for more information about change streams.
The Collection must be configured with read concern majority or no read concern for a change stream to be created successfully.
The pipeline parameter must be an array of documents, each representing a pipeline stage. The pipeline cannot be nil but can be empty. The stage documents must all be non-nil. See https://www.mongodb.com/docs/manual/changeStreams/ for a list of pipeline stages that can be used with change streams. For a pipeline of bson.D documents, the mongo.Pipeline{} type can be used.
The opts parameter can be used to specify options for change stream creation (see the options.ChangeStreamOptions documentation).
Example ¶
package main import ( "context" "fmt" "log" "time" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { var collection *mongo.Collection // Specify a pipeline that will only match "insert" events. // Specify the MaxAwaitTimeOption to have each attempt wait two seconds for // new documents. matchStage := bson.D{{"$match", bson.D{{"operationType", "insert"}}}} opts := options.ChangeStream().SetMaxAwaitTime(2 * time.Second) changeStream, err := collection.Watch( context.TODO(), mongo.Pipeline{matchStage}, opts) if err != nil { log.Panic(err) } // Print out all change stream events in the order they're received. // See the mongo.ChangeStream documentation for more examples of using // change streams. for changeStream.Next(context.TODO()) { fmt.Println(changeStream.Current) } }
Output:
type CollectionSpecification ¶
type CollectionSpecification struct { // The collection name. Name string // The type of the collection. This will either be "collection" or "view". Type string // Whether or not the collection is readOnly. This will be false for MongoDB versions < 3.4. ReadOnly bool // The collection UUID. This field will be nil for MongoDB versions < 3.6. For versions 3.6 and higher, this will // be a bson.Binary with Subtype 4. UUID *bson.Binary // A document containing the options used to construct the collection. Options bson.Raw // An IndexSpecification instance with details about the collection's _id index. IDIndex IndexSpecification }
CollectionSpecification represents a collection in a database. This type is returned by the Database.ListCollectionSpecifications function.
type CommandError ¶
type CommandError struct { Code int32 Message string Labels []string // Categories to which the error belongs Name string // A human-readable name corresponding to the error code Wrapped error // The underlying error, if one exists. Raw bson.Raw // The original server response containing the error. }
CommandError represents a server error during execution of a command. This can be returned by any operation.
func (CommandError) Error ¶
func (e CommandError) Error() string
Error implements the error interface.
func (CommandError) HasErrorCode ¶
func (e CommandError) HasErrorCode(code int) bool
HasErrorCode returns true if the error has the specified code.
func (CommandError) HasErrorCodeWithMessage ¶
func (e CommandError) HasErrorCodeWithMessage(code int, message string) bool
HasErrorCodeWithMessage returns true if the error has the specified code and Message contains the specified message.
func (CommandError) HasErrorLabel ¶
func (e CommandError) HasErrorLabel(label string) bool
HasErrorLabel returns true if the error contains the specified label.
func (CommandError) HasErrorMessage ¶
func (e CommandError) HasErrorMessage(message string) bool
HasErrorMessage returns true if the error contains the specified message.
func (CommandError) IsMaxTimeMSExpiredError ¶
func (e CommandError) IsMaxTimeMSExpiredError() bool
IsMaxTimeMSExpiredError returns true if the error is a MaxTimeMSExpired error.
func (CommandError) Unwrap ¶
func (e CommandError) Unwrap() error
Unwrap returns the underlying error.
type Cursor ¶
type Cursor struct { // Current contains the BSON bytes of the current change document. This property is only valid until the next call // to Next or TryNext. If continued access is required, a copy must be made. Current bson.Raw // contains filtered or unexported fields }
Cursor is used to iterate over a stream of documents. Each document can be decoded into a Go type via the Decode method or accessed as raw BSON via the Current field. This type is not goroutine safe and must not be used concurrently by multiple goroutines.
func NewCursorFromDocuments ¶
func NewCursorFromDocuments(documents []interface{}, preloadedErr error, registry *bson.Registry) (*Cursor, error)
NewCursorFromDocuments creates a new Cursor pre-loaded with the provided documents, error and registry. If no registry is provided, bson.NewRegistry() will be used.
The documents parameter must be a slice of documents. The slice may be nil or empty, but all elements must be non-nil.
func (*Cursor) All ¶
All iterates the cursor and decodes each document into results. The results parameter must be a pointer to a slice. The slice pointed to by results will be completely overwritten. This method will close the cursor after retrieving all documents. If the cursor has been iterated, any previously iterated documents will not be included in results.
This method requires driver version >= 1.1.0.
Example ¶
package main import ( "context" "fmt" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" ) func main() { var cursor *mongo.Cursor var results []bson.M if err := cursor.All(context.TODO(), &results); err != nil { log.Panic(err) } fmt.Println(results) }
Output:
func (*Cursor) Close ¶
Close closes this cursor. Next and TryNext must not be called after Close has been called. Close is idempotent. After the first call, any subsequent calls will not change the state.
func (*Cursor) Decode ¶
Decode will unmarshal the current document into val and return any errors from the unmarshalling process without any modification. If val is nil or is a typed nil, an error will be returned.
func (*Cursor) Err ¶
Err returns the last error seen by the Cursor, or nil if no error has occurred.
func (*Cursor) ID ¶
ID returns the ID of this cursor, or 0 if the cursor has been closed or exhausted.
func (*Cursor) Next ¶
Next gets the next document for this cursor. It returns true if there were no errors and the cursor has not been exhausted.
Next blocks until a document is available or an error occurs. If the context expires, the cursor's error will be set to ctx.Err(). In case of an error, Next will return false.
If Next returns false, subsequent calls will also return false.
Example ¶
package main import ( "context" "fmt" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" ) func main() { var cursor *mongo.Cursor defer cursor.Close(context.TODO()) // Iterate the cursor and print out each document until the cursor is // exhausted or there is an error getting the next document. for cursor.Next(context.TODO()) { // A new result variable should be declared for each document. var result bson.M if err := cursor.Decode(&result); err != nil { log.Panic(err) } fmt.Println(result) } if err := cursor.Err(); err != nil { log.Panic(err) } }
Output:
func (*Cursor) RemainingBatchLength ¶
RemainingBatchLength returns the number of documents left in the current batch. If this returns zero, the subsequent call to Next or TryNext will do a network request to fetch the next batch.
Example ¶
package main import ( "context" "fmt" "time" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { // Because we're using a tailable cursor, this must be a handle to a capped // collection. var coll *mongo.Collection // Create a tailable await cursor. Specify the MaxAwaitTime option so // requests to get more data will return if there are no documents available // after two seconds. findOpts := options.Find(). SetCursorType(options.TailableAwait). SetMaxAwaitTime(2 * time.Second) cursor, err := coll.Find(context.TODO(), bson.D{}, findOpts) if err != nil { panic(err) } for { // Iterate the cursor using TryNext. if cursor.TryNext(context.TODO()) { fmt.Println(cursor.Current) } // Handle cursor errors or the cursor being closed by the server. if err = cursor.Err(); err != nil { panic(err) } if cursor.ID() == 0 { panic("cursor was unexpectedly closed by the server") } // Use the RemainingBatchLength function to rate-limit the number of // network requests the driver does. If the current batch is empty, // sleep for a short amount of time to let documents build up on the // server before the next TryNext call, which will do a network request. if cursor.RemainingBatchLength() == 0 { time.Sleep(100 * time.Millisecond) } } }
Output:
func (*Cursor) SetBatchSize ¶
SetBatchSize sets the number of documents to fetch from the database with each iteration of the cursor's "Next" method. Note that some operations set an initial cursor batch size, so this setting only affects subsequent document batches fetched from the database.
func (*Cursor) SetComment ¶
func (c *Cursor) SetComment(comment interface{})
SetComment will set a user-configurable comment that can be used to identify the operation in server logs.
func (*Cursor) SetMaxAwaitTime ¶
SetMaxAwaitTime will set the maximum amount of time the server will allow the operations to execute. The server will error if this field is set but the cursor is not configured with awaitData=true.
The time.Duration value passed by this setter will be converted and rounded down to the nearest millisecond.
func (*Cursor) TryNext ¶
TryNext attempts to get the next document for this cursor. It returns true if there were no errors and the next document is available. This is only recommended for use with tailable cursors as a non-blocking alternative to Next. See https://www.mongodb.com/docs/manual/core/tailable-cursors/ for more information about tailable cursors.
TryNext returns false if the cursor is exhausted, an error occurs when getting results from the server, the next document is not yet available, or ctx expires. If the context expires, the cursor's error will be set to ctx.Err().
If TryNext returns false and an error occurred or the cursor has been exhausted (i.e. c.Err() != nil || c.ID() == 0), subsequent attempts will also return false. Otherwise, it is safe to call TryNext again until a document is available.
This method requires driver version >= 1.2.0.
Example ¶
package main import ( "context" "fmt" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" ) func main() { var cursor *mongo.Cursor defer cursor.Close(context.TODO()) // Iterate the cursor and print out each document until the cursor is // exhausted or there is an error getting the next document. for { if cursor.TryNext(context.TODO()) { // A new result variable should be declared for each document. var result bson.M if err := cursor.Decode(&result); err != nil { log.Panic(err) } fmt.Println(result) continue } // If TryNext returns false, the next document is not yet available, the // cursor was exhausted and was closed, or an error occurred. TryNext // should only be called again for the empty batch case. if err := cursor.Err(); err != nil { log.Panic(err) } if cursor.ID() == 0 { break } } }
Output:
type Database ¶
type Database struct {
// contains filtered or unexported fields
}
Database is a handle to a MongoDB database. It is safe for concurrent use by multiple goroutines.
func (*Database) Aggregate ¶
func (db *Database) Aggregate( ctx context.Context, pipeline interface{}, opts ...options.Lister[options.AggregateOptions], ) (*Cursor, error)
Aggregate executes an aggregate command the database. This requires MongoDB version >= 3.6 and driver version >= 1.1.0.
The pipeline parameter must be a slice of documents, each representing an aggregation stage. The pipeline cannot be nil but can be empty. The stage documents must all be non-nil. For a pipeline of bson.D documents, the mongo.Pipeline type can be used. See https://www.mongodb.com/docs/manual/reference/operator/aggregation-pipeline/#db-aggregate-stages for a list of valid stages in database-level aggregations.
The opts parameter can be used to specify options for this operation (see the options.AggregateOptions documentation).
For more information about the command, see https://www.mongodb.com/docs/manual/reference/command/aggregate/.
func (*Database) Collection ¶
func (db *Database) Collection(name string, opts ...options.Lister[options.CollectionOptions]) *Collection
Collection gets a handle for a collection with the given name configured with the given CollectionOptions.
func (*Database) CreateCollection ¶
func (db *Database) CreateCollection(ctx context.Context, name string, opts ...options.Lister[options.CreateCollectionOptions]) error
CreateCollection executes a create command to explicitly create a new collection with the specified name on the server. If the collection being created already exists, this method will return a mongo.CommandError. This method requires driver version 1.4.0 or higher.
The opts parameter can be used to specify options for the operation (see the options.CreateCollectionOptions documentation).
For more information about the command, see https://www.mongodb.com/docs/manual/reference/command/create/.
Example ¶
package main import ( "context" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { var db *mongo.Database // Create a "users" collection with a JSON schema validator. The validator // will ensure that each document in the collection has "name" and "age" // fields. jsonSchema := bson.M{ "bsonType": "object", "required": []string{"name", "age"}, "properties": bson.M{ "name": bson.M{ "bsonType": "string", "description": "the name of the user, which is required and " + "must be a string", }, "age": bson.M{ "bsonType": "int", "minimum": 18, "description": "the age of the user, which is required and " + "must be an integer >= 18", }, }, } validator := bson.M{ "$jsonSchema": jsonSchema, } opts := options.CreateCollection().SetValidator(validator) err := db.CreateCollection(context.TODO(), "users", opts) if err != nil { log.Panic(err) } }
Output:
func (*Database) CreateView ¶
func (db *Database) CreateView(ctx context.Context, viewName, viewOn string, pipeline interface{}, opts ...options.Lister[options.CreateViewOptions]) error
CreateView executes a create command to explicitly create a view on the server. See https://www.mongodb.com/docs/manual/core/views/ for more information about views. This method requires driver version >= 1.4.0 and MongoDB version >= 3.4.
The viewName parameter specifies the name of the view to create.
The viewOn parameter specifies the name of the collection or view on which this view will be created ¶
The pipeline parameter specifies an aggregation pipeline that will be exececuted against the source collection or view to create this view.
The opts parameter can be used to specify options for the operation (see the options.CreateViewOptions documentation).
Example ¶
package main import ( "context" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { var db *mongo.Database // Create a view on the "users" collection called "usernames". Specify a // pipeline that concatenates the "firstName" and "lastName" fields from // each document in "users" and projects the result into the "fullName" // field in the view. projectStage := bson.D{ {"$project", bson.D{ {"_id", 0}, {"fullName", bson.D{ {"$concat", []string{"$firstName", " ", "$lastName"}}, }}, }}, } pipeline := mongo.Pipeline{projectStage} // Specify the Collation option to set a default collation for the view. opts := options.CreateView().SetCollation(&options.Collation{ Locale: "en_US", }) err := db.CreateView(context.TODO(), "usernames", "users", pipeline, opts) if err != nil { log.Panic(err) } }
Output:
func (*Database) Drop ¶
Drop drops the database on the server. This method ignores "namespace not found" errors so it is safe to drop a database that does not exist on the server.
func (*Database) GridFSBucket ¶
func (db *Database) GridFSBucket(opts ...options.Lister[options.BucketOptions]) *GridFSBucket
GridFSBucket is used to construct a GridFS bucket which can be used as a container for files.
func (*Database) ListCollectionNames ¶
func (db *Database) ListCollectionNames( ctx context.Context, filter interface{}, opts ...options.Lister[options.ListCollectionsOptions], ) ([]string, error)
ListCollectionNames executes a listCollections command and returns a slice containing the names of the collections in the database. This method requires driver version >= 1.1.0.
The filter parameter must be a document containing query operators and can be used to select which collections are included in the result. It cannot be nil. An empty document (e.g. bson.D{}) should be used to include all collections.
The opts parameter can be used to specify options for the operation (see the options.ListCollectionsOptions documentation).
For more information about the command, see https://www.mongodb.com/docs/manual/reference/command/listCollections/.
BUG(benjirewis): ListCollectionNames prevents listing more than 100 collections per database when running against MongoDB version 2.6.
Example ¶
package main import ( "context" "fmt" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" ) func main() { var db *mongo.Database // Use a filter to only select capped collections. result, err := db.ListCollectionNames( context.TODO(), bson.D{{"options.capped", true}}) if err != nil { log.Panic(err) } for _, coll := range result { fmt.Println(coll) } }
Output:
func (*Database) ListCollectionSpecifications ¶
func (db *Database) ListCollectionSpecifications( ctx context.Context, filter interface{}, opts ...options.Lister[options.ListCollectionsOptions], ) ([]CollectionSpecification, error)
ListCollectionSpecifications executes a listCollections command and returns a slice of CollectionSpecification instances representing the collections in the database.
The filter parameter must be a document containing query operators and can be used to select which collections are included in the result. It cannot be nil. An empty document (e.g. bson.D{}) should be used to include all collections.
The opts parameter can be used to specify options for the operation (see the options.ListCollectionsOptions documentation).
For more information about the command, see https://www.mongodb.com/docs/manual/reference/command/listCollections/.
func (*Database) ListCollections ¶
func (db *Database) ListCollections( ctx context.Context, filter interface{}, opts ...options.Lister[options.ListCollectionsOptions], ) (*Cursor, error)
ListCollections executes a listCollections command and returns a cursor over the collections in the database.
The filter parameter must be a document containing query operators and can be used to select which collections are included in the result. It cannot be nil. An empty document (e.g. bson.D{}) should be used to include all collections.
The opts parameter can be used to specify options for the operation (see the options.ListCollectionsOptions documentation).
For more information about the command, see https://www.mongodb.com/docs/manual/reference/command/listCollections/.
BUG(benjirewis): ListCollections prevents listing more than 100 collections per database when running against MongoDB version 2.6.
func (*Database) RunCommand ¶
func (db *Database) RunCommand( ctx context.Context, runCommand interface{}, opts ...options.Lister[options.RunCmdOptions], ) *SingleResult
RunCommand executes the given command against the database.
This function does not obey the Database's readPreference. To specify a read preference, the RunCmdOptions.ReadPreference option must be used.
This function does not obey the Database's readConcern or writeConcern. A user must supply these values manually in the user-provided runCommand parameter.
The runCommand parameter must be a document for the command to be executed. It cannot be nil. This must be an order-preserving type such as bson.D. Map types such as bson.M are not valid.
The opts parameter can be used to specify options for this operation (see the options.RunCmdOptions documentation).
The behavior of RunCommand is undefined if the command document contains any of the following: - A session ID or any transaction-specific fields - API versioning options when an API version is already declared on the Client - maxTimeMS when Timeout is set on the Client
Example ¶
package main import ( "context" "fmt" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" "go.mongodb.org/mongo-driver/v2/mongo/readpref" ) func main() { var db *mongo.Database // Run an explain command to see the query plan for when a "find" is // executed on collection "bar" specify the ReadPreference option to // explicitly set the read preference to primary. findCmd := bson.D{{"find", "bar"}} command := bson.D{{"explain", findCmd}} opts := options.RunCmd().SetReadPreference(readpref.Primary()) var result bson.M err := db.RunCommand(context.TODO(), command, opts).Decode(&result) if err != nil { log.Panic(err) } fmt.Println(result) }
Output:
func (*Database) RunCommandCursor ¶
func (db *Database) RunCommandCursor( ctx context.Context, runCommand interface{}, opts ...options.Lister[options.RunCmdOptions], ) (*Cursor, error)
RunCommandCursor executes the given command against the database and parses the response as a cursor. If the command being executed does not return a cursor (e.g. insert), the command will be executed on the server and an error will be returned because the server response cannot be parsed as a cursor. This function does not obey the Database's read preference. To specify a read preference, the RunCmdOptions.ReadPreference option must be used.
The runCommand parameter must be a document for the command to be executed. It cannot be nil. This must be an order-preserving type such as bson.D. Map types such as bson.M are not valid.
The opts parameter can be used to specify options for this operation (see the options.RunCmdOptions documentation).
The behavior of RunCommandCursor is undefined if the command document contains any of the following: - A session ID or any transaction-specific fields - API versioning options when an API version is already declared on the Client - maxTimeMS when Timeout is set on the Client
func (*Database) Watch ¶
func (db *Database) Watch(ctx context.Context, pipeline interface{}, opts ...options.Lister[options.ChangeStreamOptions]) (*ChangeStream, error)
Watch returns a change stream for all changes to the corresponding database. See https://www.mongodb.com/docs/manual/changeStreams/ for more information about change streams.
The Database must be configured with read concern majority or no read concern for a change stream to be created successfully.
The pipeline parameter must be a slice of documents, each representing a pipeline stage. The pipeline cannot be nil but can be empty. The stage documents must all be non-nil. See https://www.mongodb.com/docs/manual/changeStreams/ for a list of pipeline stages that can be used with change streams. For a pipeline of bson.D documents, the mongo.Pipeline{} type can be used.
The opts parameter can be used to specify options for change stream creation (see the options.ChangeStreamOptions documentation).
Example ¶
package main import ( "context" "fmt" "log" "time" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { var db *mongo.Database // Specify a pipeline that will only match "insert" events. // Specify the MaxAwaitTimeOption to have each attempt wait two seconds for // new documents. matchStage := bson.D{{"$match", bson.D{{"operationType", "insert"}}}} opts := options.ChangeStream().SetMaxAwaitTime(2 * time.Second) changeStream, err := db.Watch( context.TODO(), mongo.Pipeline{matchStage}, opts) if err != nil { log.Panic(err) } // Print out all change stream events in the order they're received. // See the mongo.ChangeStream documentation for more examples of using // change streams for changeStream.Next(context.TODO()) { fmt.Println(changeStream.Current) } }
Output:
type DatabaseSpecification ¶
type DatabaseSpecification struct { Name string // The name of the database. SizeOnDisk int64 // The total size of the database files on disk in bytes. Empty bool // Specifies whether or not the database is empty. }
DatabaseSpecification contains information for a database. This type is returned as part of ListDatabasesResult.
type DeleteManyModel ¶
DeleteManyModel is used to delete multiple documents in a BulkWrite operation.
func NewDeleteManyModel ¶
func NewDeleteManyModel() *DeleteManyModel
NewDeleteManyModel creates a new DeleteManyModel.
func (*DeleteManyModel) SetCollation ¶
func (dmm *DeleteManyModel) SetCollation(collation *options.Collation) *DeleteManyModel
SetCollation specifies a collation to use for string comparisons. The default is nil, meaning no collation will be used.
func (*DeleteManyModel) SetFilter ¶
func (dmm *DeleteManyModel) SetFilter(filter interface{}) *DeleteManyModel
SetFilter specifies a filter to use to select documents to delete. The filter must be a document containing query operators. It cannot be nil.
func (*DeleteManyModel) SetHint ¶
func (dmm *DeleteManyModel) SetHint(hint interface{}) *DeleteManyModel
SetHint specifies the index to use for the operation. This should either be the index name as a string or the index specification as a document. This option is only valid for MongoDB versions >= 4.4. Server versions >= 3.4 will return an error if this option is specified. For server versions < 3.4, the driver will return a client-side error if this option is specified. The driver will return an error if this option is specified during an unacknowledged write operation. The driver will return an error if the hint parameter is a multi-key map. The default value is nil, which means that no hint will be sent.
type DeleteOneModel ¶
DeleteOneModel is used to delete at most one document in a BulkWriteOperation.
func NewDeleteOneModel ¶
func NewDeleteOneModel() *DeleteOneModel
NewDeleteOneModel creates a new DeleteOneModel.
func (*DeleteOneModel) SetCollation ¶
func (dom *DeleteOneModel) SetCollation(collation *options.Collation) *DeleteOneModel
SetCollation specifies a collation to use for string comparisons. The default is nil, meaning no collation will be used.
func (*DeleteOneModel) SetFilter ¶
func (dom *DeleteOneModel) SetFilter(filter interface{}) *DeleteOneModel
SetFilter specifies a filter to use to select the document to delete. The filter must be a document containing query operators. It cannot be nil. If the filter matches multiple documents, one will be selected from the matching documents.
func (*DeleteOneModel) SetHint ¶
func (dom *DeleteOneModel) SetHint(hint interface{}) *DeleteOneModel
SetHint specifies the index to use for the operation. This should either be the index name as a string or the index specification as a document. This option is only valid for MongoDB versions >= 4.4. Server versions >= 3.4 will return an error if this option is specified. For server versions < 3.4, the driver will return a client-side error if this option is specified. The driver will return an error if this option is specified during an unacknowledged write operation. The driver will return an error if the hint parameter is a multi-key map. The default value is nil, which means that no hint will be sent.
type DeleteResult ¶
type DeleteResult struct { DeletedCount int64 // The number of documents deleted. // Operation performed with an acknowledged write. Values for other fields may // not be deterministic if the write operation was unacknowledged. Acknowledged bool }
DeleteResult is the result type returned by DeleteOne and DeleteMany operations.
type Dialer ¶
type Dialer interface {
DialContext(ctx context.Context, network, address string) (net.Conn, error)
}
Dialer is used to make network connections.
type DistinctResult ¶
type DistinctResult struct {
// contains filtered or unexported fields
}
DistinctResult represents an array of BSON data returned from an operation. If the operation resulted in an error, all DistinctResult methods will return that error. If the operation did not return any data, all DistinctResult methods will return ErrNoDocuments.
func (*DistinctResult) Decode ¶
func (dr *DistinctResult) Decode(v any) error
Decode will unmarshal the array represented by this DistinctResult into v. If there was an error from the operation that created this DistinctReuslt, that error will be returned. If the operation returned no array, Decode will return ErrNoDocuments.
If the operation was successful and returned an array, Decode will return any errors from the unmarshalling process without any modification. If v is nil or is a typed nil, an error will be returned.
func (*DistinctResult) Err ¶
func (dr *DistinctResult) Err() error
Err provides a way to check for query errors without calling Decode. Err returns the error, if any, that was encountered while running the operation. If the operation was successful but did not return any documents, Err returns ErrNoDocuments. If this error is not nil, this error will also be returned from Decode.
func (*DistinctResult) Raw ¶
func (dr *DistinctResult) Raw() (bson.RawArray, error)
Raw returns the document represented by this DistinctResult as a bson.Raw. If there was an error from the operation that created this DistinctResult, both the result and that error will be returned. If the operation returned no documents, this will return (nil, ErrNoDocuments).
type EncryptionKeyVaultError ¶
type EncryptionKeyVaultError struct {
Wrapped error
}
EncryptionKeyVaultError represents an error while communicating with the key vault collection during client-side encryption.
func (EncryptionKeyVaultError) Error ¶
func (ekve EncryptionKeyVaultError) Error() string
Error implements the error interface.
func (EncryptionKeyVaultError) Unwrap ¶
func (ekve EncryptionKeyVaultError) Unwrap() error
Unwrap returns the underlying error.
type ErrMapForOrderedArgument ¶
type ErrMapForOrderedArgument struct {
ParamName string
}
ErrMapForOrderedArgument is returned when a map with multiple keys is passed to a CRUD method for an ordered parameter
func (ErrMapForOrderedArgument) Error ¶
func (e ErrMapForOrderedArgument) Error() string
Error implements the error interface.
type GridFSBucket ¶
type GridFSBucket struct {
// contains filtered or unexported fields
}
GridFSBucket represents a GridFS bucket.
func (*GridFSBucket) Delete ¶
func (b *GridFSBucket) Delete(ctx context.Context, fileID interface{}) error
Delete deletes all chunks and metadata associated with the file with the given file ID and runs the underlying delete operations with the provided context.
Example ¶
package main import ( "context" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" ) func main() { var bucket *mongo.GridFSBucket var fileID bson.ObjectID if err := bucket.Delete(context.Background(), fileID); err != nil { log.Panic(err) } }
Output:
func (*GridFSBucket) DownloadToStream ¶
func (b *GridFSBucket) DownloadToStream(ctx context.Context, fileID interface{}, stream io.Writer) (int64, error)
DownloadToStream downloads the file with the specified fileID and writes it to the provided io.Writer. Returns the number of bytes written to the stream and an error, or nil if there was no error.
If this download requires a custom read deadline to be set on the bucket, it cannot be done concurrently with other read operations operations on this bucket that also require a custom deadline.
The context provided to this method controls the entire lifetime of an upload stream io.Writer. If the context does set a deadline, then the client-level timeout will be used to cap the lifetime of the stream.
Example ¶
package main import ( "bytes" "context" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" ) func main() { var bucket *mongo.GridFSBucket var fileID bson.ObjectID ctx := context.Background() fileBuffer := bytes.NewBuffer(nil) if _, err := bucket.DownloadToStream(ctx, fileID, fileBuffer); err != nil { log.Panic(err) } }
Output:
func (*GridFSBucket) DownloadToStreamByName ¶
func (b *GridFSBucket) DownloadToStreamByName( ctx context.Context, filename string, stream io.Writer, opts ...options.Lister[options.GridFSNameOptions], ) (int64, error)
DownloadToStreamByName downloads the file with the given name to the given io.Writer.
If this download requires a custom read deadline to be set on the bucket, it cannot be done concurrently with other read operations operations on this bucket that also require a custom deadline.
The context provided to this method controls the entire lifetime of an upload stream io.Writer. If the context does set a deadline, then the client-level timeout will be used to cap the lifetime of the stream.
func (*GridFSBucket) Drop ¶
func (b *GridFSBucket) Drop(ctx context.Context) error
Drop drops the files and chunks collections associated with this bucket and runs the drop operations with the provided context.
Example ¶
package main import ( "context" "log" "go.mongodb.org/mongo-driver/v2/mongo" ) func main() { var bucket *mongo.GridFSBucket if err := bucket.Drop(context.Background()); err != nil { log.Panic(err) } }
Output:
func (*GridFSBucket) Find ¶
func (b *GridFSBucket) Find( ctx context.Context, filter interface{}, opts ...options.Lister[options.GridFSFindOptions], ) (*Cursor, error)
Find returns the files collection documents that match the given filter and runs the underlying find query with the provided context.
Example ¶
package main import ( "context" "fmt" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" ) func main() { var bucket *mongo.GridFSBucket // Specify a filter to find all files with a length greater than 1000 bytes. filter := bson.D{ {"length", bson.D{{"$gt", 1000}}}, } cursor, err := bucket.Find(context.Background(), filter) if err != nil { log.Panic(err) } defer func() { if err := cursor.Close(context.TODO()); err != nil { log.Panic(err) } }() type gridfsFile struct { Name string `bson:"filename"` Length int64 `bson:"length"` } var foundFiles []gridfsFile if err = cursor.All(context.TODO(), &foundFiles); err != nil { log.Panic(err) } for _, file := range foundFiles { fmt.Printf("filename: %s, length: %d\n", file.Name, file.Length) } }
Output:
func (*GridFSBucket) GetChunksCollection ¶
func (b *GridFSBucket) GetChunksCollection() *Collection
GetChunksCollection returns a handle to the collection that stores the file chunks for this bucket.
func (*GridFSBucket) GetFilesCollection ¶
func (b *GridFSBucket) GetFilesCollection() *Collection
GetFilesCollection returns a handle to the collection that stores the file documents for this bucket.
func (*GridFSBucket) OpenDownloadStream ¶
func (b *GridFSBucket) OpenDownloadStream(ctx context.Context, fileID interface{}) (*GridFSDownloadStream, error)
OpenDownloadStream creates a stream from which the contents of the file can be read.
The context provided to this method controls the entire lifetime of an upload stream io.Writer. If the context does set a deadline, then the client-level timeout will be used to cap the lifetime of the stream.
Example ¶
package main import ( "bytes" "context" "io" "log" "time" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" ) func main() { var bucket *mongo.GridFSBucket var fileID bson.ObjectID // Use WithContext to force a timeout if the download does not succeed in // 2 seconds. ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second) defer cancel() downloadStream, err := bucket.OpenDownloadStream(ctx, fileID) if err != nil { log.Panic(err) } defer func() { if err := downloadStream.Close(); err != nil { log.Panic(err) } }() fileBuffer := bytes.NewBuffer(nil) if _, err := io.Copy(fileBuffer, downloadStream); err != nil { log.Panic(err) } }
Output:
func (*GridFSBucket) OpenDownloadStreamByName ¶
func (b *GridFSBucket) OpenDownloadStreamByName( ctx context.Context, filename string, opts ...options.Lister[options.GridFSNameOptions], ) (*GridFSDownloadStream, error)
OpenDownloadStreamByName opens a download stream for the file with the given filename.
The context provided to this method controls the entire lifetime of an upload stream io.Writer. If the context does set a deadline, then the client-level timeout will be used to cap the lifetime of the stream.
func (*GridFSBucket) OpenUploadStream ¶
func (b *GridFSBucket) OpenUploadStream( ctx context.Context, filename string, opts ...options.Lister[options.GridFSUploadOptions], ) (*GridFSUploadStream, error)
OpenUploadStream creates a file ID new upload stream for a file given the filename.
The context provided to this method controls the entire lifetime of an upload stream io.Writer. If the context does set a deadline, then the client-level timeout will be used to cap the lifetime of the stream.
Example ¶
package main import ( "context" "log" "time" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { var fileContent []byte var bucket *mongo.GridFSBucket // Specify the Metadata option to include a "metadata" field in the files // collection document. uploadOpts := options.GridFSUpload(). SetMetadata(bson.D{{"metadata tag", "tag"}}) // Use WithContext to force a timeout if the upload does not succeed in // 2 seconds. ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second) defer cancel() uploadStream, err := bucket.OpenUploadStream(ctx, "filename", uploadOpts) if err != nil { log.Panic(err) } defer func() { if err = uploadStream.Close(); err != nil { log.Panic(err) } }() if _, err = uploadStream.Write(fileContent); err != nil { log.Panic(err) } }
Output:
func (*GridFSBucket) OpenUploadStreamWithID ¶
func (b *GridFSBucket) OpenUploadStreamWithID( ctx context.Context, fileID interface{}, filename string, opts ...options.Lister[options.GridFSUploadOptions], ) (*GridFSUploadStream, error)
OpenUploadStreamWithID creates a new upload stream for a file given the file ID and filename.
The context provided to this method controls the entire lifetime of an upload stream io.Writer. If the context does set a deadline, then the client-level timeout will be used to cap the lifetime of the stream.
func (*GridFSBucket) Rename ¶
func (b *GridFSBucket) Rename(ctx context.Context, fileID interface{}, newFilename string) error
Rename renames the stored file with the specified file ID.
Example ¶
package main import ( "context" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" ) func main() { var bucket *mongo.GridFSBucket var fileID bson.ObjectID ctx := context.Background() if err := bucket.Rename(ctx, fileID, "new file name"); err != nil { log.Panic(err) } }
Output:
func (*GridFSBucket) UploadFromStream ¶
func (b *GridFSBucket) UploadFromStream( ctx context.Context, filename string, source io.Reader, opts ...options.Lister[options.GridFSUploadOptions], ) (bson.ObjectID, error)
UploadFromStream creates a fileID and uploads a file given a source stream.
If this upload requires a custom write deadline to be set on the bucket, it cannot be done concurrently with other write operations operations on this bucket that also require a custom deadline.
The context provided to this method controls the entire lifetime of an upload stream io.Writer. If the context does set a deadline, then the client-level timeout will be used to cap the lifetime of the stream.
Example ¶
package main import ( "bytes" "context" "fmt" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { var fileContent []byte var bucket *mongo.GridFSBucket // Specify the Metadata option to include a "metadata" field in the files // collection document. uploadOpts := options.GridFSUpload(). SetMetadata(bson.D{{"metadata tag", "tag"}}) fileID, err := bucket.UploadFromStream( context.Background(), "filename", bytes.NewBuffer(fileContent), uploadOpts) if err != nil { log.Panic(err) } fmt.Printf("new file created with ID %s", fileID) }
Output:
func (*GridFSBucket) UploadFromStreamWithID ¶
func (b *GridFSBucket) UploadFromStreamWithID( ctx context.Context, fileID interface{}, filename string, source io.Reader, opts ...options.Lister[options.GridFSUploadOptions], ) error
UploadFromStreamWithID uploads a file given a source stream.
If this upload requires a custom write deadline to be set on the bucket, it cannot be done concurrently with other write operations operations on this bucket that also require a custom deadline.
The context provided to this method controls the entire lifetime of an upload stream io.Writer. If the context does set a deadline, then the client-level timeout will be used to cap the lifetime of the stream.
type GridFSDownloadStream ¶
type GridFSDownloadStream struct {
// contains filtered or unexported fields
}
GridFSDownloadStream is a io.Reader that can be used to download a file from a GridFS bucket.
func (*GridFSDownloadStream) Close ¶
func (ds *GridFSDownloadStream) Close() error
Close closes this download stream.
func (*GridFSDownloadStream) GetFile ¶
func (ds *GridFSDownloadStream) GetFile() *GridFSFile
GetFile returns a File object representing the file being downloaded.
type GridFSFile ¶
type GridFSFile struct { // ID is the file's ID. This will match the file ID specified when uploading the file. If an upload helper that // does not require a file ID was used, this field will be a primitive.ObjectID. ID interface{} // Length is the length of this file in bytes. Length int64 // ChunkSize is the maximum number of bytes for each chunk in this file. ChunkSize int32 // UploadDate is the time this file was added to GridFS in UTC. This field is set by the driver and is not configurable. // The Metadata field can be used to store a custom date. UploadDate time.Time // Name is the name of this file. Name string // Metadata is additional data that was specified when creating this file. This field can be unmarshalled into a // custom type using the bson.Unmarshal family of functions. Metadata bson.Raw }
GridFSFile represents a file stored in GridFS. This type can be used to access file information when downloading using the GridFSDownloadStream.GetFile method.
type GridFSUploadStream ¶
type GridFSUploadStream struct { FileID interface{} // contains filtered or unexported fields }
GridFSUploadStream is used to upload a file in chunks. This type implements the io.Writer interface and a file can be uploaded using the Write method. After an upload is complete, the Close method must be called to write file metadata.
func (*GridFSUploadStream) Abort ¶
func (us *GridFSUploadStream) Abort() error
Abort closes the stream and deletes all file chunks that have already been written.
func (*GridFSUploadStream) Close ¶
func (us *GridFSUploadStream) Close() error
Close writes file metadata to the files collection and cleans up any resources associated with the UploadStream.
type IndexModel ¶
type IndexModel struct { // A document describing which keys should be used for the index. It cannot be nil. This must be an order-preserving // type such as bson.D. Map types such as bson.M are not valid. See https://www.mongodb.com/docs/manual/indexes/#indexes // for examples of valid documents. Keys interface{} // The options to use to create the index. Options *options.IndexOptionsBuilder }
IndexModel represents a new index to be created.
type IndexSpecification ¶
type IndexSpecification struct { // The index name. Name string // The namespace for the index. This is a string in the format "databaseName.collectionName". Namespace string // The keys specification document for the index. KeysDocument bson.Raw // The index version. Version int32 // The length of time, in seconds, for documents to remain in the collection. The default value is 0, which means // that documents will remain in the collection until they're explicitly deleted or the collection is dropped. ExpireAfterSeconds *int32 // If true, the index will only reference documents that contain the fields specified in the index. The default is // false. Sparse *bool // If true, the collection will not accept insertion or update of documents where the index key value matches an // existing value in the index. The default is false. Unique *bool // The clustered index. Clustered *bool }
IndexSpecification represents an index in a database. This type is returned by the IndexView.ListSpecifications function and is also used in the CollectionSpecification type.
type IndexView ¶
type IndexView struct {
// contains filtered or unexported fields
}
IndexView is a type that can be used to create, drop, and list indexes on a collection. An IndexView for a collection can be created by a call to Collection.Indexes().
func (IndexView) CreateMany ¶
func (iv IndexView) CreateMany( ctx context.Context, models []IndexModel, opts ...options.Lister[options.CreateIndexesOptions], ) ([]string, error)
CreateMany executes a createIndexes command to create multiple indexes on the collection and returns the names of the new indexes.
For each IndexModel in the models parameter, the index name can be specified via the Options field. If a name is not given, it will be generated from the Keys document.
The opts parameter can be used to specify options for this operation (see the options.CreateIndexesOptions documentation).
For more information about the command, see https://www.mongodb.com/docs/manual/reference/command/createIndexes/.
Example ¶
package main import ( "context" "fmt" "log" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options" ) func main() { var indexView *mongo.IndexView // Create two indexes: {name: 1, email: 1} and {name: 1, age: 1} // For the first index, specify no options. The name will be generated as // "name_1_email_1" by the driver. // For the second index, specify the Name option to explicitly set the name // to "nameAge". models := []mongo.IndexModel{ { Keys: bson.D{{"name", 1}, {"email", 1}}, }, { Keys: bson.D{{"name", 1}, {"age", 1}}, Options: options.Index().SetName("nameAge"), }, } // Specify the MaxTime option to limit the amount of time the operation can // run on the server names, err := indexView.CreateMany(context.TODO(), models, nil) if err != nil { log.Panic(err) } fmt.Printf("created indexes %v\n", names) }
Output:
func (IndexView) CreateOne ¶
func (iv IndexView) CreateOne( ctx context.Context, model IndexModel, opts ...options.Lister[options.CreateIndexesOptions], ) (string, error)
CreateOne executes a createIndexes command to create an index on the collection and returns the name of the new index. See the IndexView.CreateMany documentation for more information and an example.
func (IndexView) DropAll ¶
func (iv IndexView) DropAll( ctx context.Context, opts ...options.Lister[options.DropIndexesOptions], ) error
DropAll executes a dropIndexes operation to drop all indexes on the collection.
The opts parameter can be used to specify options for this operation (see the options.DropIndexesOptions documentation).
For more information about the command, see https://www.mongodb.com/docs/manual/reference/command/dropIndexes/.
func (IndexView) DropOne ¶
func (iv IndexView) DropOne( ctx context.Context, name string, opts ...options.Lister[options.DropIndexesOptions], ) error
DropOne executes a dropIndexes operation to drop an index on the collection.
The name parameter should be the name of the index to drop. If the name is "*", ErrMultipleIndexDrop will be returned without running the command because doing so would drop all indexes.
The opts parameter can be used to specify options for this operation (see the options.DropIndexesOptions documentation).
For more information about the command, see https://www.mongodb.com/docs/manual/reference/command/dropIndexes/.
func (IndexView) DropWithKey ¶
func (iv IndexView) DropWithKey(ctx context.Context, keySpecDocument interface{}, opts ...options.Lister[options.DropIndexesOptions]) error
DropWithKey drops a collection index by key using the dropIndexes operation.
This function is useful to drop an index using its key specification instead of its name.
func (IndexView) List ¶
func (iv IndexView) List(ctx context.Context, opts ...options.Lister[options.ListIndexesOptions]) (*Cursor, error)
List executes a listIndexes command and returns a cursor over the indexes in the collection.
The opts parameter can be used to specify options for this operation (see the options.ListIndexesOptions documentation).
For more information about the command, see https://www.mongodb.com/docs/manual/reference/command/listIndexes/.
Example ¶
package main import ( "context" "fmt" "log" "time" "go.mongodb.org/mongo-driver/v2/bson" "go.mongodb.org/mongo-driver/v2/mongo" ) func main() { var indexView *mongo.IndexView // Specify a timeout to limit the amount of time the operation can run on // the server. ctx, cancel := context.WithTimeout(context.TODO(), time.Second) defer cancel() cursor, err := indexView.List(ctx, nil) if err != nil { log.Panic(err) } // Get a slice of all indexes returned and print them out. var results []bson.M if err = cursor.All(ctx, &results); err != nil { log.Panic(err) } fmt.Println(results) }
Output:
func (IndexView) ListSpecifications ¶
func (iv IndexView) ListSpecifications( ctx context.Context, opts ...options.Lister[options.ListIndexesOptions], ) ([]IndexSpecification, error)
ListSpecifications executes a List command and returns a slice of returned IndexSpecifications
type InsertManyResult ¶
type InsertManyResult struct { // The _id values of the inserted documents. Values generated by the driver will be of type bson.ObjectID. InsertedIDs []interface{} // Operation performed with an acknowledged write. Values for other fields may // not be deterministic if the write operation was unacknowledged. Acknowledged bool }
InsertManyResult is a result type returned by an InsertMany operation.
type InsertOneModel ¶
type InsertOneModel struct {
Document interface{}
}
InsertOneModel is used to insert a single document in a BulkWrite operation.
func NewInsertOneModel ¶
func NewInsertOneModel() *InsertOneModel
NewInsertOneModel creates a new InsertOneModel.
func (*InsertOneModel) SetDocument ¶
func (iom *InsertOneModel) SetDocument(doc interface{}) *InsertOneModel
SetDocument specifies the document to be inserted. The document cannot be nil. If it does not have an _id field when transformed into BSON, one will be added automatically to the marshalled document. The original document will not be modified.
type InsertOneResult ¶
type InsertOneResult struct { // The _id of the inserted document. A value generated by the driver will be of type bson.ObjectID. InsertedID interface{} // Operation performed with an acknowledged write. Values for other fields may // not be deterministic if the write operation was unacknowledged. Acknowledged bool }
InsertOneResult is the result type returned by an InsertOne operation.
type LabeledError ¶
type LabeledError interface { error // HasErrorLabel returns true if the error contains the specified label. HasErrorLabel(string) bool }
LabeledError is an interface for errors with labels.
type ListDatabasesResult ¶
type ListDatabasesResult struct { // A slice containing one DatabaseSpecification for each database matched by the operation's filter. Databases []DatabaseSpecification // The total size of the database files of the returned databases in bytes. // This will be the sum of the SizeOnDisk field for each specification in Databases. TotalSize int64 }
ListDatabasesResult is a result of a ListDatabases operation.
type MarshalError ¶
type MarshalError struct { Value interface{} Err error }
MarshalError is returned when attempting to marshal a value into a document results in an error.
func (MarshalError) Error ¶
func (me MarshalError) Error() string
Error implements the error interface.
type MongocryptError ¶
MongocryptError represents an libmongocrypt error during client-side encryption.
func (MongocryptError) Error ¶
func (m MongocryptError) Error() string
Error implements the error interface.
type MongocryptdError ¶
type MongocryptdError struct {
Wrapped error
}
MongocryptdError represents an error while communicating with mongocryptd during client-side encryption.
func (MongocryptdError) Error ¶
func (e MongocryptdError) Error() string
Error implements the error interface.
func (MongocryptdError) Unwrap ¶
func (e MongocryptdError) Unwrap() error
Unwrap returns the underlying error.
type Pipeline ¶
Pipeline is a type that makes creating aggregation pipelines easier. It is a helper and is intended for serializing to BSON.
Example usage:
mongo.Pipeline{ {{"$group", bson.D{{"_id", "$state"}, {"totalPop", bson.D{{"$sum", "$pop"}}}}}}, {{"$match", bson.D{{"totalPop", bson.D{{"$gte", 10*1000*1000}}}}}}, }
type ReplaceOneModel ¶
type ReplaceOneModel struct { Collation *options.Collation Upsert *bool Filter interface{} Replacement interface{} Hint interface{} }
ReplaceOneModel is used to replace at most one document in a BulkWrite operation.
func NewReplaceOneModel ¶
func NewReplaceOneModel() *ReplaceOneModel
NewReplaceOneModel creates a new ReplaceOneModel.
func (*ReplaceOneModel) SetCollation ¶
func (rom *ReplaceOneModel) SetCollation(collation *options.Collation) *ReplaceOneModel
SetCollation specifies a collation to use for string comparisons. The default is nil, meaning no collation will be used.
func (*ReplaceOneModel) SetFilter ¶
func (rom *ReplaceOneModel) SetFilter(filter interface{}) *ReplaceOneModel
SetFilter specifies a filter to use to select the document to replace. The filter must be a document containing query operators. It cannot be nil. If the filter matches multiple documents, one will be selected from the matching documents.
func (*ReplaceOneModel) SetHint ¶
func (rom *ReplaceOneModel) SetHint(hint interface{}) *ReplaceOneModel
SetHint specifies the index to use for the operation. This should either be the index name as a string or the index specification as a document. This option is only valid for MongoDB versions >= 4.2. Server versions >= 3.4 will return an error if this option is specified. For server versions < 3.4, the driver will return a client-side error if this option is specified. The driver will return an error if this option is specified during an unacknowledged write operation. The driver will return an error if the hint parameter is a multi-key map. The default value is nil, which means that no hint will be sent.
func (*ReplaceOneModel) SetReplacement ¶
func (rom *ReplaceOneModel) SetReplacement(rep interface{}) *ReplaceOneModel
SetReplacement specifies a document that will be used to replace the selected document. It cannot be nil and cannot contain any update operators (https://www.mongodb.com/docs/manual/reference/operator/update/).
func (*ReplaceOneModel) SetUpsert ¶
func (rom *ReplaceOneModel) SetUpsert(upsert bool) *ReplaceOneModel
SetUpsert specifies whether or not the replacement document should be inserted if no document matching the filter is found. If an upsert is performed, the _id of the upserted document can be retrieved from the UpsertedIDs field of the BulkWriteResult.
type RewrapManyDataKeyResult ¶
type RewrapManyDataKeyResult struct {
*BulkWriteResult
}
RewrapManyDataKeyResult is the result of the bulk write operation used to update the key vault collection with rewrapped data keys.
type SearchIndexModel ¶
type SearchIndexModel struct { // A document describing the definition for the search index. It cannot be nil. // See https://www.mongodb.com/docs/atlas/atlas-search/create-index/ for reference. Definition interface{} // The search index options. Options *options.SearchIndexesOptionsBuilder }
SearchIndexModel represents a new search index to be created.
type SearchIndexView ¶
type SearchIndexView struct {
// contains filtered or unexported fields
}
SearchIndexView is a type that can be used to create, drop, list and update search indexes on a collection. A SearchIndexView for a collection can be created by a call to Collection.SearchIndexes().
func (SearchIndexView) CreateMany ¶
func (siv SearchIndexView) CreateMany( ctx context.Context, models []SearchIndexModel, _ ...options.Lister[options.CreateSearchIndexesOptions], ) ([]string, error)
CreateMany executes a createSearchIndexes command to create multiple search indexes on the collection and returns the names of the new search indexes.
For each SearchIndexModel in the models parameter, the index name can be specified.
The opts parameter can be used to specify options for this operation (see the options.CreateSearchIndexesOptions documentation).
func (SearchIndexView) CreateOne ¶
func (siv SearchIndexView) CreateOne( ctx context.Context, model SearchIndexModel, opts ...options.Lister[options.CreateSearchIndexesOptions], ) (string, error)
CreateOne executes a createSearchIndexes command to create a search index on the collection and returns the name of the new search index. See the SearchIndexView.CreateMany documentation for more information and an example.
func (SearchIndexView) DropOne ¶
func (siv SearchIndexView) DropOne( ctx context.Context, name string, _ ...options.Lister[options.DropSearchIndexOptions], ) error
DropOne executes a dropSearchIndexes operation to drop a search index on the collection.
The name parameter should be the name of the search index to drop. If the name is "*", ErrMultipleIndexDrop will be returned without running the command because doing so would drop all search indexes.
The opts parameter can be used to specify options for this operation (see the options.DropSearchIndexOptions documentation).
func (SearchIndexView) List ¶
func (siv SearchIndexView) List( ctx context.Context, searchIdxOpts options.Lister[options.SearchIndexesOptions], opts ...options.Lister[options.ListSearchIndexesOptions], ) (*Cursor, error)
List executes a listSearchIndexes command and returns a cursor over the search indexes in the collection.
The name parameter specifies the index name. A nil pointer matches all indexes.
The opts parameter can be used to specify options for this operation (see the options.ListSearchIndexesOptions documentation).
func (SearchIndexView) UpdateOne ¶
func (siv SearchIndexView) UpdateOne( ctx context.Context, name string, definition interface{}, _ ...options.Lister[options.UpdateSearchIndexOptions], ) error
UpdateOne executes a updateSearchIndex operation to update a search index on the collection.
The name parameter should be the name of the search index to update.
The definition parameter is a document describing the definition for the search index. It cannot be nil.
The opts parameter can be used to specify options for this operation (see the options.UpdateSearchIndexOptions documentation).
type ServerError ¶
type ServerError interface { LabeledError // HasErrorCode returns true if the error has the specified code. HasErrorCode(int) bool // HasErrorMessage returns true if the error contains the specified message. HasErrorMessage(string) bool // HasErrorCodeWithMessage returns true if any of the contained errors have the specified code and message. HasErrorCodeWithMessage(int, string) bool // contains filtered or unexported methods }
ServerError is the interface implemented by errors returned from the server. Custom implementations of this interface should not be used in production.
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session is a MongoDB logical session. Sessions can be used to enable causal consistency for a group of operations or to execute operations in an ACID transaction. A new Session can be created from a Client instance. A Session created from a Client must only be used to execute operations using that Client or a Database or Collection created from that Client. For more information about sessions, and their use cases, see https://www.mongodb.com/docs/manual/reference/server-sessions/, https://www.mongodb.com/docs/manual/core/read-isolation-consistency-recency/#causal-consistency, and https://www.mongodb.com/docs/manual/core/transactions/.
Implementations of Session are not safe for concurrent use by multiple goroutines.
func SessionFromContext ¶
SessionFromContext extracts the mongo.Session object stored in a Context. This can be used on a SessionContext that was created implicitly through one of the callback-based session APIs or explicitly by calling NewSessionContext. If there is no Session stored in the provided Context, nil is returned.
func (*Session) AbortTransaction ¶
AbortTransaction aborts the active transaction for this session. This method returns an error if there is no active transaction for this session or if the transaction has been committed or aborted.
func (*Session) AdvanceClusterTime ¶
AdvanceClusterTime advances the cluster time for a session. This method returns an error if the session has ended.
func (*Session) AdvanceOperationTime ¶
AdvanceOperationTime advances the operation time for a session. This method returns an error if the session has ended.
func (*Session) ClientSession
deprecated
func (*Session) ClusterTime ¶
ClusterTime returns the current cluster time document associated with the session.
func (*Session) CommitTransaction ¶
CommitTransaction commits the active transaction for this session. This method returns an error if there is no active transaction for this session or if the transaction has been aborted.
func (*Session) EndSession ¶
EndSession aborts any existing transactions and close the session.
func (*Session) ID ¶
ID returns the current ID document associated with the session. The ID document is in the form {"id": <BSON binary value>}.
func (*Session) OperationTime ¶
OperationTime returns the current operation time document associated with the session.
func (*Session) StartTransaction ¶
StartTransaction starts a new transaction. This method returns an error if there is already a transaction in-progress for this session.
func (*Session) WithTransaction ¶
func (s *Session) WithTransaction( ctx context.Context, fn func(ctx context.Context) (interface{}, error), opts ...options.Lister[options.TransactionOptions], ) (interface{}, error)
WithTransaction starts a transaction on this session and runs the fn callback. Errors with the TransientTransactionError and UnknownTransactionCommitResult labels are retried for up to 120 seconds. Inside the callback, the SessionContext must be used as the Context parameter for any operations that should be part of the transaction. If the ctx parameter already has a Session attached to it, it will be replaced by this session. The fn callback may be run multiple times during WithTransaction due to retry attempts, so it must be idempotent. Non-retryable operation errors or any operation errors that occur after the timeout expires will be returned without retrying. If the callback fails, the driver will call AbortTransaction. Because this method must succeed to ensure that server-side resources are properly cleaned up, context deadlines and cancellations will not be respected during this call. For a usage example, see the Client.StartSession method documentation.
type SingleResult ¶
type SingleResult struct { // Operation performed with an acknowledged write. Values returned by // SingleResult methods may not be deterministic if the write operation was // unacknowledged and so should not be relied upon. Acknowledged bool // contains filtered or unexported fields }
SingleResult represents a single document returned from an operation. If the operation resulted in an error, all SingleResult methods will return that error. If the operation did not return any documents, all SingleResult methods will return ErrNoDocuments.
func NewSingleResultFromDocument ¶
func NewSingleResultFromDocument( document interface{}, err error, registry *bson.Registry, ) *SingleResult
NewSingleResultFromDocument creates a SingleResult with the provided error, registry, and an underlying Cursor pre-loaded with the provided document, error and registry. If no registry is provided, bson.NewRegistry() will be used. If an error distinct from the one provided occurs during creation of the SingleResult, that error will be stored on the returned SingleResult.
The document parameter must be a non-nil document.
func (*SingleResult) Decode ¶
func (sr *SingleResult) Decode(v interface{}) error
Decode will unmarshal the document represented by this SingleResult into v. If there was an error from the operation that created this SingleResult, that error will be returned. If the operation returned no documents, Decode will return ErrNoDocuments.
If the operation was successful and returned a document, Decode will return any errors from the unmarshalling process without any modification. If v is nil or is a typed nil, an error will be returned.
func (*SingleResult) Err ¶
func (sr *SingleResult) Err() error
Err provides a way to check for query errors without calling Decode. Err returns the error, if any, that was encountered while running the operation. If the operation was successful but did not return any documents, Err returns ErrNoDocuments. If this error is not nil, this error will also be returned from Decode.
func (*SingleResult) Raw ¶
func (sr *SingleResult) Raw() (bson.Raw, error)
Raw returns the document represented by this SingleResult as a bson.Raw. If there was an error from the operation that created this SingleResult, both the result and that error will be returned. If the operation returned no documents, this will return (nil, ErrNoDocuments).
type StreamType ¶
type StreamType uint8
StreamType represents the cluster type against which a ChangeStream was created.
const ( CollectionStream StreamType = iota DatabaseStream ClientStream )
These constants represent valid change stream types. A change stream can be initialized over a collection, all collections in a database, or over a cluster.
type UpdateManyModel ¶
type UpdateManyModel struct { Collation *options.Collation Upsert *bool Filter interface{} Update interface{} ArrayFilters []interface{} Hint interface{} }
UpdateManyModel is used to update multiple documents in a BulkWrite operation.
func NewUpdateManyModel ¶
func NewUpdateManyModel() *UpdateManyModel
NewUpdateManyModel creates a new UpdateManyModel.
func (*UpdateManyModel) SetArrayFilters ¶
func (umm *UpdateManyModel) SetArrayFilters(filters []interface{}) *UpdateManyModel
SetArrayFilters specifies a set of filters to determine which elements should be modified when updating an array field.
func (*UpdateManyModel) SetCollation ¶
func (umm *UpdateManyModel) SetCollation(collation *options.Collation) *UpdateManyModel
SetCollation specifies a collation to use for string comparisons. The default is nil, meaning no collation will be used.
func (*UpdateManyModel) SetFilter ¶
func (umm *UpdateManyModel) SetFilter(filter interface{}) *UpdateManyModel
SetFilter specifies a filter to use to select documents to update. The filter must be a document containing query operators. It cannot be nil.
func (*UpdateManyModel) SetHint ¶
func (umm *UpdateManyModel) SetHint(hint interface{}) *UpdateManyModel
SetHint specifies the index to use for the operation. This should either be the index name as a string or the index specification as a document. This option is only valid for MongoDB versions >= 4.2. Server versions >= 3.4 will return an error if this option is specified. For server versions < 3.4, the driver will return a client-side error if this option is specified. The driver will return an error if this option is specified during an unacknowledged write operation. The driver will return an error if the hint parameter is a multi-key map. The default value is nil, which means that no hint will be sent.
func (*UpdateManyModel) SetUpdate ¶
func (umm *UpdateManyModel) SetUpdate(update interface{}) *UpdateManyModel
SetUpdate specifies the modifications to be made to the selected documents. The value must be a document containing update operators (https://www.mongodb.com/docs/manual/reference/operator/update/). It cannot be nil or empty.
func (*UpdateManyModel) SetUpsert ¶
func (umm *UpdateManyModel) SetUpsert(upsert bool) *UpdateManyModel
SetUpsert specifies whether or not a new document should be inserted if no document matching the filter is found. If an upsert is performed, the _id of the upserted document can be retrieved from the UpsertedIDs field of the BulkWriteResult.
type UpdateOneModel ¶
type UpdateOneModel struct { Collation *options.Collation Upsert *bool Filter interface{} Update interface{} ArrayFilters []interface{} Hint interface{} }
UpdateOneModel is used to update at most one document in a BulkWrite operation.
func NewUpdateOneModel ¶
func NewUpdateOneModel() *UpdateOneModel
NewUpdateOneModel creates a new UpdateOneModel.
func (*UpdateOneModel) SetArrayFilters ¶
func (uom *UpdateOneModel) SetArrayFilters(filters []interface{}) *UpdateOneModel
SetArrayFilters specifies a set of filters to determine which elements should be modified when updating an array field.
func (*UpdateOneModel) SetCollation ¶
func (uom *UpdateOneModel) SetCollation(collation *options.Collation) *UpdateOneModel
SetCollation specifies a collation to use for string comparisons. The default is nil, meaning no collation will be used.
func (*UpdateOneModel) SetFilter ¶
func (uom *UpdateOneModel) SetFilter(filter interface{}) *UpdateOneModel
SetFilter specifies a filter to use to select the document to update. The filter must be a document containing query operators. It cannot be nil. If the filter matches multiple documents, one will be selected from the matching documents.
func (*UpdateOneModel) SetHint ¶
func (uom *UpdateOneModel) SetHint(hint interface{}) *UpdateOneModel
SetHint specifies the index to use for the operation. This should either be the index name as a string or the index specification as a document. This option is only valid for MongoDB versions >= 4.2. Server versions >= 3.4 will return an error if this option is specified. For server versions < 3.4, the driver will return a client-side error if this option is specified. The driver will return an error if this option is specified during an unacknowledged write operation. The driver will return an error if the hint parameter is a multi-key map. The default value is nil, which means that no hint will be sent.
func (*UpdateOneModel) SetUpdate ¶
func (uom *UpdateOneModel) SetUpdate(update interface{}) *UpdateOneModel
SetUpdate specifies the modifications to be made to the selected document. The value must be a document containing update operators (https://www.mongodb.com/docs/manual/reference/operator/update/). It cannot be nil or empty.
func (*UpdateOneModel) SetUpsert ¶
func (uom *UpdateOneModel) SetUpsert(upsert bool) *UpdateOneModel
SetUpsert specifies whether or not a new document should be inserted if no document matching the filter is found. If an upsert is performed, the _id of the upserted document can be retrieved from the UpsertedIDs field of the BulkWriteResult.
type UpdateResult ¶
type UpdateResult struct { MatchedCount int64 // The number of documents matched by the filter. ModifiedCount int64 // The number of documents modified by the operation. UpsertedCount int64 // The number of documents upserted by the operation. UpsertedID interface{} // The _id field of the upserted document, or nil if no upsert was done. // Operation performed with an acknowledged write. Values for other fields may // not be deterministic if the write operation was unacknowledged. Acknowledged bool }
UpdateResult is the result type returned from UpdateOne, UpdateMany, and ReplaceOne operations.
type WriteConcernError ¶
type WriteConcernError struct { Name string Code int Message string Details bson.Raw Raw bson.Raw // The original write concern error from the server response. }
WriteConcernError represents a write concern failure during execution of a write operation. This error type is only returned as part of a WriteException or a BulkWriteException.
func (WriteConcernError) Error ¶
func (wce WriteConcernError) Error() string
Error implements the error interface.
func (WriteConcernError) IsMaxTimeMSExpiredError ¶
func (wce WriteConcernError) IsMaxTimeMSExpiredError() bool
IsMaxTimeMSExpiredError returns true if the error is a MaxTimeMSExpired error.
type WriteError ¶
type WriteError struct { // The index of the write in the slice passed to an InsertMany or BulkWrite operation that caused this error. Index int Code int Message string Details bson.Raw // The original write error from the server response. Raw bson.Raw }
WriteError is an error that occurred during execution of a write operation. This error type is only returned as part of a WriteException or BulkWriteException.
func (WriteError) Error ¶
func (we WriteError) Error() string
func (WriteError) HasErrorCode ¶
func (we WriteError) HasErrorCode(code int) bool
HasErrorCode returns true if the error has the specified code.
func (WriteError) HasErrorCodeWithMessage ¶
func (we WriteError) HasErrorCodeWithMessage(code int, message string) bool
HasErrorCodeWithMessage returns true if the error has the specified code and Message contains the specified message.
func (WriteError) HasErrorLabel ¶
func (we WriteError) HasErrorLabel(string) bool
HasErrorLabel returns true if the error contains the specified label. WriteErrors do not contain labels, so we always return false.
func (WriteError) HasErrorMessage ¶
func (we WriteError) HasErrorMessage(message string) bool
HasErrorMessage returns true if the error contains the specified message.
type WriteErrors ¶
type WriteErrors []WriteError
WriteErrors is a group of write errors that occurred during execution of a write operation.
func (WriteErrors) Error ¶
func (we WriteErrors) Error() string
Error implements the error interface.
type WriteException ¶
type WriteException struct { // The write concern error that occurred, or nil if there was none. WriteConcernError *WriteConcernError // The write errors that occurred during operation execution. WriteErrors WriteErrors // The categories to which the exception belongs. Labels []string // The original server response containing the error. Raw bson.Raw }
WriteException is the error type returned by the InsertOne, DeleteOne, DeleteMany, UpdateOne, UpdateMany, and ReplaceOne operations.
func (WriteException) Error ¶
func (mwe WriteException) Error() string
Error implements the error interface.
func (WriteException) HasErrorCode ¶
func (mwe WriteException) HasErrorCode(code int) bool
HasErrorCode returns true if the error has the specified code.
func (WriteException) HasErrorCodeWithMessage ¶
func (mwe WriteException) HasErrorCodeWithMessage(code int, message string) bool
HasErrorCodeWithMessage returns true if any of the contained errors have the specified code and message.
func (WriteException) HasErrorLabel ¶
func (mwe WriteException) HasErrorLabel(label string) bool
HasErrorLabel returns true if the error contains the specified label.
func (WriteException) HasErrorMessage ¶
func (mwe WriteException) HasErrorMessage(message string) bool
HasErrorMessage returns true if the error contains the specified message.
type WriteModel ¶
type WriteModel interface {
// contains filtered or unexported methods
}
WriteModel is an interface implemented by models that can be used in a BulkWrite operation. Each WriteModel represents a write.
This interface is implemented by InsertOneModel, DeleteOneModel, DeleteManyModel, ReplaceOneModel, UpdateOneModel, and UpdateManyModel. Custom implementations of this interface must not be used.
Notes ¶
Bugs ¶
ListCollections prevents listing more than 100 collections per database when running against MongoDB version 2.6.
ListCollectionNames prevents listing more than 100 collections per database when running against MongoDB version 2.6.
Source Files ¶
- background_context.go
- batch_cursor.go
- bulk_write.go
- bulk_write_models.go
- change_stream.go
- change_stream_deployment.go
- client.go
- client_encryption.go
- collection.go
- crypt_retrievers.go
- cursor.go
- database.go
- doc.go
- errors.go
- gridfs_bucket.go
- gridfs_download_stream.go
- gridfs_upload_stream.go
- index_view.go
- mongo.go
- mongocryptd.go
- results.go
- search_index_view.go
- session.go
- single_result.go
Directories ¶
Path | Synopsis |
---|---|
Package address provides structured representations of network addresses.
|
Package address provides structured representations of network addresses. |
Package options defines the optional configurations for the MongoDB Go Driver.
|
Package options defines the optional configurations for the MongoDB Go Driver. |
Package readconcern defines read concerns for MongoDB operations.
|
Package readconcern defines read concerns for MongoDB operations. |
Package readpref defines read preferences for MongoDB queries.
|
Package readpref defines read preferences for MongoDB queries. |
Package writeconcern defines write concerns for MongoDB operations.
|
Package writeconcern defines write concerns for MongoDB operations. |