Wala shell

Advanced PHP File Manager

Server IP: 127.0.0.1 | PHP Version: 8.3.30 | Domains Hosted: 54

Name	Size	Last Modified
📁 ..	-	2025-05-25 12:27
📁 address	-	2025-05-25 12:27
📄 background_context.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import "context" // backgroundContext is an implementation of the context.Context interface that wraps a child Context. Value requests // are forwarded to the child Context but the Done and Err functions are overridden to ensure the new context does not // time out or get cancelled. type backgroundContext struct { context.Context childValuesCtx context.Context } // newBackgroundContext creates a new Context whose behavior matches that of context.Background(), but Value calls are // forwarded to the provided ctx parameter. If ctx is nil, context.Background() is returned. func newBackgroundContext(ctx context.Context) context.Context { if ctx == nil { return context.Background() } return &backgroundContext{ Context: context.Background(), childValuesCtx: ctx, } } func (b *backgroundContext) Value(key interface{}) interface{} { return b.childValuesCtx.Value(key) }	1.15 KB	2025-05-25 12:27
📄 background_context_test.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "context" "testing" "time" "go.mongodb.org/mongo-driver/internal/assert" ) func TestBackgroundContext(t testing.T) { t.Run("newBackgroundContext accepts a nil child", func(t testing.T) { ctx := newBackgroundContext(nil) assert.Equal(t, context.Background(), ctx, "expected context.Background() for a nil child") }) t.Run("Value requests are forwarded", func(t testing.T) { // Tests the Value function. type ctxKey struct{} expectedVal := "value" childCtx := context.WithValue(context.Background(), ctxKey{}, expectedVal) ctx := newBackgroundContext(childCtx) gotVal, ok := ctx.Value(ctxKey{}).(string) assert.True(t, ok, "expected context to contain a string value for ctxKey") assert.Equal(t, expectedVal, gotVal, "expected value for ctxKey to be %q, got %q", expectedVal, gotVal) }) t.Run("background context does not have a deadline", func(t testing.T) { // Tests the Deadline function. childCtx, cancel := context.WithTimeout(context.Background(), time.Second) defer cancel() ctx := newBackgroundContext(childCtx) deadline, ok := ctx.Deadline() assert.False(t, ok, "expected context to have no deadline, but got %v", deadline) }) t.Run("background context cannot be cancelled", func(t *testing.T) { // Tests the Done and Err functions. childCtx, cancel := context.WithCancel(context.Background()) cancel() ctx := newBackgroundContext(childCtx) select { case <-ctx.Done(): t.Fatalf("expected context to not expire, but Done channel had a value; ctx error: %v", ctx.Err()) default: } assert.Nil(t, ctx.Err(), "expected context error to be nil, got %v", ctx.Err()) }) }	1.9 KB	2025-05-25 12:27
📄 batch_cursor.go // Copyright (C) MongoDB, Inc. 2022-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "context" "time" "go.mongodb.org/mongo-driver/x/bsonx/bsoncore" "go.mongodb.org/mongo-driver/x/mongo/driver" ) // batchCursor is the interface implemented by types that can provide batches of document results. // The Cursor type is built on top of this type. type batchCursor interface { // ID returns the ID of the cursor. ID() int64 // Next returns true if there is a batch available. Next(context.Context) bool // Batch will return a DocumentSequence for the current batch of documents. The returned // DocumentSequence is only valid until the next call to Next or Close. Batch() *bsoncore.DocumentSequence // Server returns a pointer to the cursor's server. Server() driver.Server // Err returns the last error encountered. Err() error // Close closes the cursor. Close(context.Context) error // SetBatchSize is a modifier function used to adjust the batch size of // the cursor that implements it. SetBatchSize(int32) // SetMaxTime 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. SetMaxTime(time.Duration) // SetComment will set a user-configurable comment that can be used to // identify the operation in server logs. SetComment(interface{}) } // changeStreamCursor is the interface implemented by batch cursors that also provide the functionality for retrieving // a postBatchResumeToken from commands and allows for the cursor to be killed rather than closed type changeStreamCursor interface { batchCursor // PostBatchResumeToken returns the latest seen post batch resume token. PostBatchResumeToken() bsoncore.Document // KillCursor kills cursor on server without closing batch cursor KillCursor(context.Context) error }	2.18 KB	2025-05-25 12:27
📄 bson_helpers_test.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "testing" "go.mongodb.org/mongo-driver/bson" "go.mongodb.org/mongo-driver/internal/assert" ) // compare expected and actual BSON documents. comparison succeeds if actual contains each element in expected. func compareDocuments(t testing.T, expected, actual bson.Raw) { t.Helper() eElems, err := expected.Elements() assert.Nil(t, err, "error getting expected elements: %v", err) for _, e := range eElems { eKey := e.Key() aVal, err := actual.LookupErr(eKey) assert.Nil(t, err, "key %s not found in result", e.Key()) compareBsonValues(t, eKey, e.Value(), aVal) } } func numberFromValue(t testing.T, val bson.RawValue) int64 { switch val.Type { case bson.TypeInt32: return int64(val.Int32()) case bson.TypeInt64: return val.Int64() case bson.TypeDouble: return int64(val.Double()) default: t.Fatalf("unexpected type for number: %v", val.Type) } return 0 } func compareNumberValues(t testing.T, key string, expected, actual bson.RawValue) { eInt := numberFromValue(t, expected) aInt := numberFromValue(t, actual) assert.Equal(t, eInt, aInt, "value mismatch for key %s; expected %v, got %v", key, expected, actual) } // compare BSON values and fail if they are not equal. the key parameter is used for error strings. // if the expected value is a numeric type (int32, int64, or double) and the value is 42, the function only asserts that // the actual value is non-null. func compareBsonValues(t testing.T, key string, expected, actual bson.RawValue) { t.Helper() switch expected.Type { case bson.TypeInt32, bson.TypeInt64, bson.TypeDouble: compareNumberValues(t, key, expected, actual) case bson.TypeEmbeddedDocument: compareDocuments(t, expected.Document(), actual.Document()) case bson.TypeArray: compareDocuments(t, expected.Array(), actual.Array()) default: assert.Equal(t, expected.Value, actual.Value, "value mismatch for key %v; expected %v, got %v", key, expected.Value, actual.Value) } }	2.2 KB	2025-05-25 12:27
📄 bulk_write.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "context" "errors" "go.mongodb.org/mongo-driver/bson/bsoncodec" "go.mongodb.org/mongo-driver/bson/primitive" "go.mongodb.org/mongo-driver/mongo/description" "go.mongodb.org/mongo-driver/mongo/options" "go.mongodb.org/mongo-driver/mongo/writeconcern" "go.mongodb.org/mongo-driver/x/bsonx/bsoncore" "go.mongodb.org/mongo-driver/x/mongo/driver" "go.mongodb.org/mongo-driver/x/mongo/driver/operation" "go.mongodb.org/mongo-driver/x/mongo/driver/session" ) type bulkWriteBatch struct { models []WriteModel canRetry bool indexes []int } // bulkWrite performs a bulkwrite operation type bulkWrite struct { comment interface{} ordered bool bypassDocumentValidation bool models []WriteModel session session.Client collection Collection selector description.ServerSelector writeConcern writeconcern.WriteConcern result BulkWriteResult let interface{} } func (bw bulkWrite) execute(ctx context.Context) error { ordered := true if bw.ordered != nil { ordered = bw.ordered } batches := createBatches(bw.models, ordered) bw.result = BulkWriteResult{ UpsertedIDs: make(map[int64]interface{}), } bwErr := BulkWriteException{ WriteErrors: make([]BulkWriteError, 0), } var lastErr error continueOnError := !ordered for _, batch := range batches { if len(batch.models) == 0 { continue } batchRes, batchErr, err := bw.runBatch(ctx, batch) bw.mergeResults(batchRes) bwErr.WriteConcernError = batchErr.WriteConcernError bwErr.Labels = append(bwErr.Labels, batchErr.Labels...) bwErr.WriteErrors = append(bwErr.WriteErrors, batchErr.WriteErrors...) commandErrorOccurred := err != nil && !errors.Is(err, driver.ErrUnacknowledgedWrite) writeErrorOccurred := len(batchErr.WriteErrors) > 0 \|\| batchErr.WriteConcernError != nil if !continueOnError && (commandErrorOccurred \|\| writeErrorOccurred) { if err != nil { return err } return bwErr } if err != nil { lastErr = err } } bw.result.MatchedCount -= bw.result.UpsertedCount if lastErr != nil { _, lastErr = processWriteError(lastErr) return lastErr } if len(bwErr.WriteErrors) > 0 \|\| bwErr.WriteConcernError != nil { return bwErr } return nil } func (bw bulkWrite) runBatch(ctx context.Context, batch bulkWriteBatch) (BulkWriteResult, BulkWriteException, error) { batchRes := BulkWriteResult{ UpsertedIDs: make(map[int64]interface{}), } batchErr := BulkWriteException{} var writeErrors []driver.WriteError switch batch.models[0].(type) { case InsertOneModel: res, err := bw.runInsert(ctx, batch) if err != nil { var writeErr driver.WriteCommandError if !errors.As(err, &writeErr) { return BulkWriteResult{}, batchErr, err } writeErrors = writeErr.WriteErrors batchErr.Labels = writeErr.Labels batchErr.WriteConcernError = convertDriverWriteConcernError(writeErr.WriteConcernError) } batchRes.InsertedCount = res.N case DeleteOneModel, DeleteManyModel: res, err := bw.runDelete(ctx, batch) if err != nil { var writeErr driver.WriteCommandError if !errors.As(err, &writeErr) { return BulkWriteResult{}, batchErr, err } writeErrors = writeErr.WriteErrors batchErr.Labels = writeErr.Labels batchErr.WriteConcernError = convertDriverWriteConcernError(writeErr.WriteConcernError) } batchRes.DeletedCount = res.N case ReplaceOneModel, UpdateOneModel, UpdateManyModel: res, err := bw.runUpdate(ctx, batch) if err != nil { var writeErr driver.WriteCommandError if !errors.As(err, &writeErr) { return BulkWriteResult{}, batchErr, err } writeErrors = writeErr.WriteErrors batchErr.Labels = writeErr.Labels batchErr.WriteConcernError = convertDriverWriteConcernError(writeErr.WriteConcernError) } batchRes.MatchedCount = res.N batchRes.ModifiedCount = res.NModified batchRes.UpsertedCount = int64(len(res.Upserted)) for _, upsert := range res.Upserted { batchRes.UpsertedIDs[int64(batch.indexes[upsert.Index])] = upsert.ID } } batchErr.WriteErrors = make([]BulkWriteError, 0, len(writeErrors)) convWriteErrors := writeErrorsFromDriverWriteErrors(writeErrors) for _, we := range convWriteErrors { request := batch.models[we.Index] we.Index = batch.indexes[we.Index] batchErr.WriteErrors = append(batchErr.WriteErrors, BulkWriteError{ WriteError: we, Request: request, }) } return batchRes, batchErr, nil } func (bw bulkWrite) runInsert(ctx context.Context, batch bulkWriteBatch) (operation.InsertResult, error) { docs := make([]bsoncore.Document, len(batch.models)) var i int for _, model := range batch.models { converted := model.(InsertOneModel) doc, err := marshal(converted.Document, bw.collection.bsonOpts, bw.collection.registry) if err != nil { return operation.InsertResult{}, err } doc, _, err = ensureID(doc, primitive.NilObjectID, bw.collection.bsonOpts, bw.collection.registry) if err != nil { return operation.InsertResult{}, err } docs[i] = doc i++ } op := operation.NewInsert(docs...). Session(bw.session).WriteConcern(bw.writeConcern).CommandMonitor(bw.collection.client.monitor). ServerSelector(bw.selector).ClusterClock(bw.collection.client.clock). Database(bw.collection.db.name).Collection(bw.collection.name). Deployment(bw.collection.client.deployment).Crypt(bw.collection.client.cryptFLE). ServerAPI(bw.collection.client.serverAPI).Timeout(bw.collection.client.timeout). Logger(bw.collection.client.logger) if bw.comment != nil { comment, err := marshalValue(bw.comment, bw.collection.bsonOpts, bw.collection.registry) if err != nil { return op.Result(), err } op.Comment(comment) } if bw.bypassDocumentValidation != nil && bw.bypassDocumentValidation { op = op.BypassDocumentValidation(bw.bypassDocumentValidation) } if bw.ordered != nil { op = op.Ordered(bw.ordered) } retry := driver.RetryNone if bw.collection.client.retryWrites && batch.canRetry { retry = driver.RetryOncePerCommand } op = op.Retry(retry) err := op.Execute(ctx) return op.Result(), err } func (bw bulkWrite) runDelete(ctx context.Context, batch bulkWriteBatch) (operation.DeleteResult, error) { docs := make([]bsoncore.Document, len(batch.models)) var i int var hasHint bool for _, model := range batch.models { var doc bsoncore.Document var err error switch converted := model.(type) { case DeleteOneModel: doc, err = createDeleteDoc( converted.Filter, converted.Collation, converted.Hint, true, bw.collection.bsonOpts, bw.collection.registry) hasHint = hasHint \|\| (converted.Hint != nil) case DeleteManyModel: doc, err = createDeleteDoc( converted.Filter, converted.Collation, converted.Hint, false, bw.collection.bsonOpts, bw.collection.registry) hasHint = hasHint \|\| (converted.Hint != nil) } if err != nil { return operation.DeleteResult{}, err } docs[i] = doc i++ } op := operation.NewDelete(docs...). Session(bw.session).WriteConcern(bw.writeConcern).CommandMonitor(bw.collection.client.monitor). ServerSelector(bw.selector).ClusterClock(bw.collection.client.clock). Database(bw.collection.db.name).Collection(bw.collection.name). Deployment(bw.collection.client.deployment).Crypt(bw.collection.client.cryptFLE).Hint(hasHint). ServerAPI(bw.collection.client.serverAPI).Timeout(bw.collection.client.timeout). Logger(bw.collection.client.logger) if bw.comment != nil { comment, err := marshalValue(bw.comment, bw.collection.bsonOpts, bw.collection.registry) if err != nil { return op.Result(), err } op.Comment(comment) } if bw.let != nil { let, err := marshal(bw.let, bw.collection.bsonOpts, bw.collection.registry) if err != nil { return operation.DeleteResult{}, err } op = op.Let(let) } if bw.ordered != nil { op = op.Ordered(bw.ordered) } retry := driver.RetryNone if bw.collection.client.retryWrites && batch.canRetry { retry = driver.RetryOncePerCommand } op = op.Retry(retry) err := op.Execute(ctx) return op.Result(), err } func createDeleteDoc( filter interface{}, collation options.Collation, hint interface{}, deleteOne bool, bsonOpts options.BSONOptions, registry bsoncodec.Registry, ) (bsoncore.Document, error) { f, err := marshal(filter, bsonOpts, registry) if err != nil { return nil, err } var limit int32 if deleteOne { limit = 1 } didx, doc := bsoncore.AppendDocumentStart(nil) doc = bsoncore.AppendDocumentElement(doc, "q", f) doc = bsoncore.AppendInt32Element(doc, "limit", limit) if collation != nil { doc = bsoncore.AppendDocumentElement(doc, "collation", collation.ToDocument()) } if hint != nil { if isUnorderedMap(hint) { return nil, ErrMapForOrderedArgument{"hint"} } hintVal, err := marshalValue(hint, bsonOpts, registry) if err != nil { return nil, err } doc = bsoncore.AppendValueElement(doc, "hint", hintVal) } doc, _ = bsoncore.AppendDocumentEnd(doc, didx) return doc, nil } func (bw bulkWrite) runUpdate(ctx context.Context, batch bulkWriteBatch) (operation.UpdateResult, error) { docs := make([]bsoncore.Document, len(batch.models)) var hasHint bool var hasArrayFilters bool for i, model := range batch.models { var doc bsoncore.Document var err error switch converted := model.(type) { case ReplaceOneModel: doc, err = createUpdateDoc( converted.Filter, converted.Replacement, converted.Hint, nil, converted.Collation, converted.Upsert, false, false, bw.collection.bsonOpts, bw.collection.registry) hasHint = hasHint \|\| (converted.Hint != nil) case UpdateOneModel: doc, err = createUpdateDoc( converted.Filter, converted.Update, converted.Hint, converted.ArrayFilters, converted.Collation, converted.Upsert, false, true, bw.collection.bsonOpts, bw.collection.registry) hasHint = hasHint \|\| (converted.Hint != nil) hasArrayFilters = hasArrayFilters \|\| (converted.ArrayFilters != nil) case UpdateManyModel: doc, err = createUpdateDoc( converted.Filter, converted.Update, converted.Hint, converted.ArrayFilters, converted.Collation, converted.Upsert, true, true, bw.collection.bsonOpts, bw.collection.registry) hasHint = hasHint \|\| (converted.Hint != nil) hasArrayFilters = hasArrayFilters \|\| (converted.ArrayFilters != nil) } if err != nil { return operation.UpdateResult{}, err } docs[i] = doc } op := operation.NewUpdate(docs...). Session(bw.session).WriteConcern(bw.writeConcern).CommandMonitor(bw.collection.client.monitor). ServerSelector(bw.selector).ClusterClock(bw.collection.client.clock). Database(bw.collection.db.name).Collection(bw.collection.name). Deployment(bw.collection.client.deployment).Crypt(bw.collection.client.cryptFLE).Hint(hasHint). ArrayFilters(hasArrayFilters).ServerAPI(bw.collection.client.serverAPI). Timeout(bw.collection.client.timeout).Logger(bw.collection.client.logger) if bw.comment != nil { comment, err := marshalValue(bw.comment, bw.collection.bsonOpts, bw.collection.registry) if err != nil { return op.Result(), err } op.Comment(comment) } if bw.let != nil { let, err := marshal(bw.let, bw.collection.bsonOpts, bw.collection.registry) if err != nil { return operation.UpdateResult{}, err } op = op.Let(let) } if bw.ordered != nil { op = op.Ordered(bw.ordered) } if bw.bypassDocumentValidation != nil && bw.bypassDocumentValidation { op = op.BypassDocumentValidation(bw.bypassDocumentValidation) } retry := driver.RetryNone if bw.collection.client.retryWrites && batch.canRetry { retry = driver.RetryOncePerCommand } op = op.Retry(retry) err := op.Execute(ctx) return op.Result(), err } func createUpdateDoc( filter interface{}, update interface{}, hint interface{}, arrayFilters options.ArrayFilters, collation options.Collation, upsert bool, multi bool, checkDollarKey bool, bsonOpts options.BSONOptions, registry bsoncodec.Registry, ) (bsoncore.Document, error) { f, err := marshal(filter, bsonOpts, registry) if err != nil { return nil, err } uidx, updateDoc := bsoncore.AppendDocumentStart(nil) updateDoc = bsoncore.AppendDocumentElement(updateDoc, "q", f) u, err := marshalUpdateValue(update, bsonOpts, registry, checkDollarKey) if err != nil { return nil, err } updateDoc = bsoncore.AppendValueElement(updateDoc, "u", u) if multi { updateDoc = bsoncore.AppendBooleanElement(updateDoc, "multi", multi) } if arrayFilters != nil { reg := registry if arrayFilters.Registry != nil { reg = arrayFilters.Registry } arr, err := marshalValue(arrayFilters.Filters, bsonOpts, reg) if err != nil { return nil, err } updateDoc = bsoncore.AppendArrayElement(updateDoc, "arrayFilters", arr.Data) } if collation != nil { updateDoc = bsoncore.AppendDocumentElement(updateDoc, "collation", bsoncore.Document(collation.ToDocument())) } if upsert != nil { updateDoc = bsoncore.AppendBooleanElement(updateDoc, "upsert", upsert) } if hint != nil { if isUnorderedMap(hint) { return nil, ErrMapForOrderedArgument{"hint"} } hintVal, err := marshalValue(hint, bsonOpts, registry) if err != nil { return nil, err } updateDoc = bsoncore.AppendValueElement(updateDoc, "hint", hintVal) } updateDoc, _ = bsoncore.AppendDocumentEnd(updateDoc, uidx) return updateDoc, nil } func createBatches(models []WriteModel, ordered bool) []bulkWriteBatch { if ordered { return createOrderedBatches(models) } batches := make([]bulkWriteBatch, 5) batches[insertCommand].canRetry = true batches[deleteOneCommand].canRetry = true batches[updateOneCommand].canRetry = true // TODO(GODRIVER-1157): fix batching once operation retryability is fixed for i, model := range models { switch model.(type) { case InsertOneModel: batches[insertCommand].models = append(batches[insertCommand].models, model) batches[insertCommand].indexes = append(batches[insertCommand].indexes, i) case DeleteOneModel: batches[deleteOneCommand].models = append(batches[deleteOneCommand].models, model) batches[deleteOneCommand].indexes = append(batches[deleteOneCommand].indexes, i) case DeleteManyModel: batches[deleteManyCommand].models = append(batches[deleteManyCommand].models, model) batches[deleteManyCommand].indexes = append(batches[deleteManyCommand].indexes, i) case ReplaceOneModel, UpdateOneModel: batches[updateOneCommand].models = append(batches[updateOneCommand].models, model) batches[updateOneCommand].indexes = append(batches[updateOneCommand].indexes, i) case UpdateManyModel: batches[updateManyCommand].models = append(batches[updateManyCommand].models, model) batches[updateManyCommand].indexes = append(batches[updateManyCommand].indexes, i) } } return batches } func createOrderedBatches(models []WriteModel) []bulkWriteBatch { var batches []bulkWriteBatch var prevKind writeCommandKind = -1 i := -1 // batch index for ind, model := range models { var createNewBatch bool var canRetry bool var newKind writeCommandKind // TODO(GODRIVER-1157): fix batching once operation retryability is fixed switch model.(type) { case InsertOneModel: createNewBatch = prevKind != insertCommand canRetry = true newKind = insertCommand case DeleteOneModel: createNewBatch = prevKind != deleteOneCommand canRetry = true newKind = deleteOneCommand case DeleteManyModel: createNewBatch = prevKind != deleteManyCommand newKind = deleteManyCommand case ReplaceOneModel, UpdateOneModel: createNewBatch = prevKind != updateOneCommand canRetry = true newKind = updateOneCommand case UpdateManyModel: createNewBatch = prevKind != updateManyCommand newKind = updateManyCommand } if createNewBatch { batches = append(batches, bulkWriteBatch{ models: []WriteModel{model}, canRetry: canRetry, indexes: []int{ind}, }) i++ } else { batches[i].models = append(batches[i].models, model) if !canRetry { batches[i].canRetry = false // don't make it true if it was already false } batches[i].indexes = append(batches[i].indexes, ind) } prevKind = newKind } return batches } func (bw bulkWrite) mergeResults(newResult BulkWriteResult) { bw.result.InsertedCount += newResult.InsertedCount bw.result.MatchedCount += newResult.MatchedCount bw.result.ModifiedCount += newResult.ModifiedCount bw.result.DeletedCount += newResult.DeletedCount bw.result.UpsertedCount += newResult.UpsertedCount for index, upsertID := range newResult.UpsertedIDs { bw.result.UpsertedIDs[index] = upsertID } } // WriteCommandKind is the type of command represented by a Write type writeCommandKind int8 // These constants represent the valid types of write commands. const ( insertCommand writeCommandKind = iota updateOneCommand updateManyCommand deleteOneCommand deleteManyCommand )	17 KB	2025-05-25 12:27
📄 bulk_write_models.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "go.mongodb.org/mongo-driver/mongo/options" ) // 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. type WriteModel interface { writeModel() } // InsertOneModel is used to insert a single document in a BulkWrite operation. type InsertOneModel struct { Document interface{} } // NewInsertOneModel creates a new InsertOneModel. func NewInsertOneModel() InsertOneModel { return &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. func (iom InsertOneModel) SetDocument(doc interface{}) InsertOneModel { iom.Document = doc return iom } func (InsertOneModel) writeModel() {} // DeleteOneModel is used to delete at most one document in a BulkWriteOperation. type DeleteOneModel struct { Filter interface{} Collation options.Collation Hint interface{} } // NewDeleteOneModel creates a new DeleteOneModel. func NewDeleteOneModel() DeleteOneModel { return &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 (dom DeleteOneModel) SetFilter(filter interface{}) DeleteOneModel { dom.Filter = filter return dom } // SetCollation specifies a collation to use for string comparisons. The default is nil, meaning no collation will be // used. func (dom DeleteOneModel) SetCollation(collation options.Collation) DeleteOneModel { dom.Collation = collation return dom } // 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. func (dom DeleteOneModel) SetHint(hint interface{}) DeleteOneModel { dom.Hint = hint return dom } func (DeleteOneModel) writeModel() {} // DeleteManyModel is used to delete multiple documents in a BulkWrite operation. type DeleteManyModel struct { Filter interface{} Collation options.Collation Hint interface{} } // NewDeleteManyModel creates a new DeleteManyModel. func NewDeleteManyModel() DeleteManyModel { return &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 (dmm DeleteManyModel) SetFilter(filter interface{}) DeleteManyModel { dmm.Filter = filter return dmm } // SetCollation specifies a collation to use for string comparisons. The default is nil, meaning no collation will be // used. func (dmm DeleteManyModel) SetCollation(collation options.Collation) DeleteManyModel { dmm.Collation = collation return dmm } // 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. func (dmm DeleteManyModel) SetHint(hint interface{}) DeleteManyModel { dmm.Hint = hint return dmm } func (DeleteManyModel) writeModel() {} // ReplaceOneModel is used to replace at most one document in a BulkWrite operation. type ReplaceOneModel struct { Collation options.Collation Upsert bool Filter interface{} Replacement interface{} Hint interface{} } // NewReplaceOneModel creates a new ReplaceOneModel. func NewReplaceOneModel() ReplaceOneModel { return &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 (rom ReplaceOneModel) SetHint(hint interface{}) ReplaceOneModel { rom.Hint = hint return rom } // 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 (rom ReplaceOneModel) SetFilter(filter interface{}) ReplaceOneModel { rom.Filter = filter return rom } // 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 (rom ReplaceOneModel) SetReplacement(rep interface{}) ReplaceOneModel { rom.Replacement = rep return rom } // SetCollation specifies a collation to use for string comparisons. The default is nil, meaning no collation will be // used. func (rom ReplaceOneModel) SetCollation(collation options.Collation) ReplaceOneModel { rom.Collation = collation return rom } // 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. func (rom ReplaceOneModel) SetUpsert(upsert bool) ReplaceOneModel { rom.Upsert = &upsert return rom } func (ReplaceOneModel) writeModel() {} // UpdateOneModel is used to update at most one document in a BulkWrite operation. type UpdateOneModel struct { Collation options.Collation Upsert bool Filter interface{} Update interface{} ArrayFilters options.ArrayFilters Hint interface{} } // NewUpdateOneModel creates a new UpdateOneModel. func NewUpdateOneModel() UpdateOneModel { return &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 (uom UpdateOneModel) SetHint(hint interface{}) UpdateOneModel { uom.Hint = hint return uom } // 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 (uom UpdateOneModel) SetFilter(filter interface{}) UpdateOneModel { uom.Filter = filter return uom } // 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 (uom UpdateOneModel) SetUpdate(update interface{}) UpdateOneModel { uom.Update = update return uom } // SetArrayFilters specifies a set of filters to determine which elements should be modified when updating an array // field. func (uom UpdateOneModel) SetArrayFilters(filters options.ArrayFilters) UpdateOneModel { uom.ArrayFilters = &filters return uom } // SetCollation specifies a collation to use for string comparisons. The default is nil, meaning no collation will be // used. func (uom UpdateOneModel) SetCollation(collation options.Collation) UpdateOneModel { uom.Collation = collation return uom } // 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. func (uom UpdateOneModel) SetUpsert(upsert bool) UpdateOneModel { uom.Upsert = &upsert return uom } func (UpdateOneModel) writeModel() {} // UpdateManyModel is used to update multiple documents in a BulkWrite operation. type UpdateManyModel struct { Collation options.Collation Upsert bool Filter interface{} Update interface{} ArrayFilters options.ArrayFilters Hint interface{} } // NewUpdateManyModel creates a new UpdateManyModel. func NewUpdateManyModel() UpdateManyModel { return &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 (umm UpdateManyModel) SetHint(hint interface{}) UpdateManyModel { umm.Hint = hint return umm } // 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 (umm UpdateManyModel) SetFilter(filter interface{}) UpdateManyModel { umm.Filter = filter return umm } // 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 (umm UpdateManyModel) SetUpdate(update interface{}) UpdateManyModel { umm.Update = update return umm } // SetArrayFilters specifies a set of filters to determine which elements should be modified when updating an array // field. func (umm UpdateManyModel) SetArrayFilters(filters options.ArrayFilters) UpdateManyModel { umm.ArrayFilters = &filters return umm } // SetCollation specifies a collation to use for string comparisons. The default is nil, meaning no collation will be // used. func (umm UpdateManyModel) SetCollation(collation options.Collation) UpdateManyModel { umm.Collation = collation return umm } // 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. func (umm UpdateManyModel) SetUpsert(upsert bool) UpdateManyModel { umm.Upsert = &upsert return umm } func (*UpdateManyModel) writeModel() {}	12.3 KB	2025-05-25 12:27
📄 change_stream.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "context" "errors" "fmt" "reflect" "strconv" "time" "go.mongodb.org/mongo-driver/bson" "go.mongodb.org/mongo-driver/bson/bsoncodec" "go.mongodb.org/mongo-driver/bson/primitive" "go.mongodb.org/mongo-driver/internal/csot" "go.mongodb.org/mongo-driver/mongo/description" "go.mongodb.org/mongo-driver/mongo/options" "go.mongodb.org/mongo-driver/mongo/readconcern" "go.mongodb.org/mongo-driver/mongo/readpref" "go.mongodb.org/mongo-driver/x/bsonx/bsoncore" "go.mongodb.org/mongo-driver/x/mongo/driver" "go.mongodb.org/mongo-driver/x/mongo/driver/operation" "go.mongodb.org/mongo-driver/x/mongo/driver/session" ) 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") minResumableLabelWireVersion int32 = 9 // Wire version at which the server includes the resumable error label networkErrorLabel = "NetworkError" resumableErrorLabel = "ResumableChangeStreamError" errorCursorNotFound int32 = 43 // CursorNotFound error code // Allowlist of error codes that are considered resumable. resumableChangeStreamErrors = map[int32]struct{}{ 6: {}, // HostUnreachable 7: {}, // HostNotFound 89: {}, // NetworkTimeout 91: {}, // ShutdownInProgress 189: {}, // PrimarySteppedDown 262: {}, // ExceededTimeLimit 9001: {}, // SocketException 10107: {}, // NotPrimary 11600: {}, // InterruptedAtShutdown 11602: {}, // InterruptedDueToReplStateChange 13435: {}, // NotPrimaryNoSecondaryOK 13436: {}, // NotPrimaryOrSecondary 63: {}, // StaleShardVersion 150: {}, // StaleEpoch 13388: {}, // StaleConfig 234: {}, // RetryChangeStream 133: {}, // FailedToSatisfyReadPreference } ) // 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/. 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 aggregate operation.Aggregate pipelineSlice []bsoncore.Document pipelineOptions map[string]bsoncore.Value cursor changeStreamCursor cursorOptions driver.CursorOptions batch []bsoncore.Document resumeToken bson.Raw err error sess session.Client client Client bsonOpts options.BSONOptions registry bsoncodec.Registry streamType StreamType options options.ChangeStreamOptions selector description.ServerSelector operationTime primitive.Timestamp wireVersion description.VersionRange } type changeStreamConfig struct { readConcern readconcern.ReadConcern readPreference readpref.ReadPref client Client bsonOpts options.BSONOptions registry bsoncodec.Registry streamType StreamType collectionName string databaseName string crypt driver.Crypt } func newChangeStream(ctx context.Context, config changeStreamConfig, pipeline interface{}, opts ...options.ChangeStreamOptions) (ChangeStream, error) { if ctx == nil { ctx = context.Background() } cursorOpts := config.client.createBaseCursorOptions() cursorOpts.MarshalValueEncoderFn = newEncoderFn(config.bsonOpts, config.registry) cs := &ChangeStream{ client: config.client, bsonOpts: config.bsonOpts, registry: config.registry, streamType: config.streamType, options: options.MergeChangeStreamOptions(opts...), selector: description.CompositeSelector([]description.ServerSelector{ description.ReadPrefSelector(config.readPreference), description.LatencySelector(config.client.localThreshold), }), cursorOptions: cursorOpts, } cs.sess = sessionFromContext(ctx) if cs.sess == nil && cs.client.sessionPool != nil { cs.sess = session.NewImplicitClientSession(cs.client.sessionPool, cs.client.id) } if cs.err = cs.client.validSession(cs.sess); cs.err != nil { closeImplicitSession(cs.sess) return nil, cs.Err() } cs.aggregate = operation.NewAggregate(nil). ReadPreference(config.readPreference).ReadConcern(config.readConcern). Deployment(cs.client.deployment).ClusterClock(cs.client.clock). CommandMonitor(cs.client.monitor).Session(cs.sess).ServerSelector(cs.selector).Retry(driver.RetryNone). ServerAPI(cs.client.serverAPI).Crypt(config.crypt).Timeout(cs.client.timeout) if cs.options.Collation != nil { cs.aggregate.Collation(bsoncore.Document(cs.options.Collation.ToDocument())) } if comment := cs.options.Comment; comment != nil { cs.aggregate.Comment(comment) commentVal, err := marshalValue(comment, cs.bsonOpts, cs.registry) if err != nil { return nil, err } cs.cursorOptions.Comment = commentVal } if cs.options.BatchSize != nil { cs.aggregate.BatchSize(cs.options.BatchSize) cs.cursorOptions.BatchSize = cs.options.BatchSize } if cs.options.MaxAwaitTime != nil { cs.cursorOptions.MaxTimeMS = int64(cs.options.MaxAwaitTime / time.Millisecond) } if cs.options.Custom != nil { // Marshal all custom options before passing to the initial aggregate. Return // any errors from Marshaling. customOptions := make(map[string]bsoncore.Value) for optionName, optionValue := range cs.options.Custom { bsonType, bsonData, err := bson.MarshalValueWithRegistry(cs.registry, optionValue) if err != nil { cs.err = err closeImplicitSession(cs.sess) return nil, cs.Err() } optionValueBSON := bsoncore.Value{Type: bsonType, Data: bsonData} customOptions[optionName] = optionValueBSON } cs.aggregate.CustomOptions(customOptions) } if cs.options.CustomPipeline != nil { // Marshal all custom pipeline options before building pipeline slice. Return // any errors from Marshaling. cs.pipelineOptions = make(map[string]bsoncore.Value) for optionName, optionValue := range cs.options.CustomPipeline { bsonType, bsonData, err := bson.MarshalValueWithRegistry(cs.registry, optionValue) if err != nil { cs.err = err closeImplicitSession(cs.sess) return nil, cs.Err() } optionValueBSON := bsoncore.Value{Type: bsonType, Data: bsonData} cs.pipelineOptions[optionName] = optionValueBSON } } switch cs.streamType { case ClientStream: cs.aggregate.Database("admin") case DatabaseStream: cs.aggregate.Database(config.databaseName) case CollectionStream: cs.aggregate.Collection(config.collectionName).Database(config.databaseName) default: closeImplicitSession(cs.sess) return nil, fmt.Errorf("must supply a valid StreamType in config, instead of %v", cs.streamType) } // When starting a change stream, cache startAfter as the first resume token if it is set. If not, cache // resumeAfter. If neither is set, do not cache a resume token. resumeToken := cs.options.StartAfter if resumeToken == nil { resumeToken = cs.options.ResumeAfter } var marshaledToken bson.Raw if resumeToken != nil { if marshaledToken, cs.err = bson.Marshal(resumeToken); cs.err != nil { closeImplicitSession(cs.sess) return nil, cs.Err() } } cs.resumeToken = marshaledToken if cs.err = cs.buildPipelineSlice(pipeline); cs.err != nil { closeImplicitSession(cs.sess) return nil, cs.Err() } var pipelineArr bsoncore.Document pipelineArr, cs.err = cs.pipelineToBSON() cs.aggregate.Pipeline(pipelineArr) if cs.err = cs.executeOperation(ctx, false); cs.err != nil { closeImplicitSession(cs.sess) return nil, cs.Err() } return cs, cs.Err() } func (cs ChangeStream) createOperationDeployment(server driver.Server, connection driver.Connection) driver.Deployment { return &changeStreamDeployment{ topologyKind: cs.client.deployment.Kind(), server: server, conn: connection, } } func (cs ChangeStream) executeOperation(ctx context.Context, resuming bool) error { var server driver.Server var conn driver.Connection if server, cs.err = cs.client.deployment.SelectServer(ctx, cs.selector); cs.err != nil { return cs.Err() } if conn, cs.err = server.Connection(ctx); cs.err != nil { return cs.Err() } defer conn.Close() cs.wireVersion = conn.Description().WireVersion cs.aggregate.Deployment(cs.createOperationDeployment(server, conn)) if resuming { cs.replaceOptions(cs.wireVersion) csOptDoc, err := cs.createPipelineOptionsDoc() if err != nil { return err } pipIdx, pipDoc := bsoncore.AppendDocumentStart(nil) pipDoc = bsoncore.AppendDocumentElement(pipDoc, "$changeStream", csOptDoc) if pipDoc, cs.err = bsoncore.AppendDocumentEnd(pipDoc, pipIdx); cs.err != nil { return cs.Err() } cs.pipelineSlice[0] = pipDoc var plArr bsoncore.Document if plArr, cs.err = cs.pipelineToBSON(); cs.err != nil { return cs.Err() } cs.aggregate.Pipeline(plArr) } // If no deadline is set on the passed-in context, cs.client.timeout is set, and context is not already // a Timeout context, honor cs.client.timeout in new Timeout context for change stream operation execution // and potential retry. if _, deadlineSet := ctx.Deadline(); !deadlineSet && cs.client.timeout != nil && !csot.IsTimeoutContext(ctx) { newCtx, cancelFunc := csot.MakeTimeoutContext(ctx, cs.client.timeout) // Redefine ctx to be the new timeout-derived context. ctx = newCtx // Cancel the timeout-derived context at the end of executeOperation to avoid a context leak. defer cancelFunc() } // Execute the aggregate, retrying on retryable errors once (1) if retryable reads are enabled and // infinitely (-1) if context is a Timeout context. var retries int if cs.client.retryReads { retries = 1 } if csot.IsTimeoutContext(ctx) { retries = -1 } var err error AggregateExecuteLoop: for { err = cs.aggregate.Execute(ctx) // If no error or no retries remain, do not retry. if err == nil \|\| retries == 0 { break AggregateExecuteLoop } switch tt := err.(type) { case driver.Error: // If error is not retryable, do not retry. if !tt.RetryableRead() { break AggregateExecuteLoop } // If error is retryable: subtract 1 from retries, redo server selection, checkout // a connection, and restart loop. retries-- server, err = cs.client.deployment.SelectServer(ctx, cs.selector) if err != nil { break AggregateExecuteLoop } conn.Close() conn, err = server.Connection(ctx) if err != nil { break AggregateExecuteLoop } defer conn.Close() // Update the wire version with data from the new connection. cs.wireVersion = conn.Description().WireVersion // Reset deployment. cs.aggregate.Deployment(cs.createOperationDeployment(server, conn)) default: // Do not retry if error is not a driver error. break AggregateExecuteLoop } } if err != nil { cs.err = replaceErrors(err) return cs.err } cr := cs.aggregate.ResultCursorResponse() cr.Server = server cs.cursor, cs.err = driver.NewBatchCursor(cr, cs.sess, cs.client.clock, cs.cursorOptions) if cs.err = replaceErrors(cs.err); cs.err != nil { return cs.Err() } cs.updatePbrtFromCommand() if cs.options.StartAtOperationTime == nil && cs.options.ResumeAfter == nil && cs.options.StartAfter == nil && cs.wireVersion.Max >= 7 && cs.emptyBatch() && cs.resumeToken == nil { cs.operationTime = cs.sess.OperationTime } return cs.Err() } // Updates the post batch resume token after a successful aggregate or getMore operation. func (cs ChangeStream) updatePbrtFromCommand() { // Only cache the pbrt if an empty batch was returned and a pbrt was included if pbrt := cs.cursor.PostBatchResumeToken(); cs.emptyBatch() && pbrt != nil { cs.resumeToken = bson.Raw(pbrt) } } func (cs ChangeStream) storeResumeToken() error { // If cs.Current is the last document in the batch and a pbrt is included, cache the pbrt // Otherwise, cache the _id of the document var tokenDoc bson.Raw if len(cs.batch) == 0 { if pbrt := cs.cursor.PostBatchResumeToken(); pbrt != nil { tokenDoc = bson.Raw(pbrt) } } if tokenDoc == nil { var ok bool tokenDoc, ok = cs.Current.Lookup("_id").DocumentOK() if !ok { _ = cs.Close(context.Background()) return ErrMissingResumeToken } } cs.resumeToken = tokenDoc return nil } func (cs ChangeStream) buildPipelineSlice(pipeline interface{}) error { val := reflect.ValueOf(pipeline) if !val.IsValid() \|\| !(val.Kind() == reflect.Slice) { cs.err = errors.New("can only marshal slices and arrays into aggregation pipelines, but got invalid") return cs.err } cs.pipelineSlice = make([]bsoncore.Document, 0, val.Len()+1) csIdx, csDoc := bsoncore.AppendDocumentStart(nil) csDocTemp, err := cs.createPipelineOptionsDoc() if err != nil { return err } csDoc = bsoncore.AppendDocumentElement(csDoc, "$changeStream", csDocTemp) csDoc, cs.err = bsoncore.AppendDocumentEnd(csDoc, csIdx) if cs.err != nil { return cs.err } cs.pipelineSlice = append(cs.pipelineSlice, csDoc) for i := 0; i < val.Len(); i++ { var elem []byte elem, cs.err = marshal(val.Index(i).Interface(), cs.bsonOpts, cs.registry) if cs.err != nil { return cs.err } cs.pipelineSlice = append(cs.pipelineSlice, elem) } return cs.err } func (cs ChangeStream) createPipelineOptionsDoc() (bsoncore.Document, error) { plDocIdx, plDoc := bsoncore.AppendDocumentStart(nil) if cs.streamType == ClientStream { plDoc = bsoncore.AppendBooleanElement(plDoc, "allChangesForCluster", true) } if cs.options.FullDocument != nil && cs.options.FullDocument != options.Default { plDoc = bsoncore.AppendStringElement(plDoc, "fullDocument", string(cs.options.FullDocument)) } if cs.options.FullDocumentBeforeChange != nil { plDoc = bsoncore.AppendStringElement(plDoc, "fullDocumentBeforeChange", string(cs.options.FullDocumentBeforeChange)) } if cs.options.ResumeAfter != nil { var raDoc bsoncore.Document raDoc, cs.err = marshal(cs.options.ResumeAfter, cs.bsonOpts, cs.registry) if cs.err != nil { return nil, cs.err } plDoc = bsoncore.AppendDocumentElement(plDoc, "resumeAfter", raDoc) } if cs.options.ShowExpandedEvents != nil { plDoc = bsoncore.AppendBooleanElement(plDoc, "showExpandedEvents", cs.options.ShowExpandedEvents) } if cs.options.StartAfter != nil { var saDoc bsoncore.Document saDoc, cs.err = marshal(cs.options.StartAfter, cs.bsonOpts, cs.registry) if cs.err != nil { return nil, cs.err } plDoc = bsoncore.AppendDocumentElement(plDoc, "startAfter", saDoc) } if cs.options.StartAtOperationTime != nil { plDoc = bsoncore.AppendTimestampElement(plDoc, "startAtOperationTime", cs.options.StartAtOperationTime.T, cs.options.StartAtOperationTime.I) } // Append custom pipeline options. for optionName, optionValue := range cs.pipelineOptions { plDoc = bsoncore.AppendValueElement(plDoc, optionName, optionValue) } if plDoc, cs.err = bsoncore.AppendDocumentEnd(plDoc, plDocIdx); cs.err != nil { return nil, cs.err } return plDoc, nil } func (cs ChangeStream) pipelineToBSON() (bsoncore.Document, error) { pipelineDocIdx, pipelineArr := bsoncore.AppendArrayStart(nil) for i, doc := range cs.pipelineSlice { pipelineArr = bsoncore.AppendDocumentElement(pipelineArr, strconv.Itoa(i), doc) } if pipelineArr, cs.err = bsoncore.AppendArrayEnd(pipelineArr, pipelineDocIdx); cs.err != nil { return nil, cs.err } return pipelineArr, cs.err } func (cs ChangeStream) replaceOptions(wireVersion description.VersionRange) { // Cached resume token: use the resume token as the resumeAfter option and set no other resume options if cs.resumeToken != nil { cs.options.SetResumeAfter(cs.resumeToken) cs.options.SetStartAfter(nil) cs.options.SetStartAtOperationTime(nil) return } // No cached resume token but cached operation time: use the operation time as the startAtOperationTime option and // set no other resume options if (cs.sess.OperationTime != nil \|\| cs.options.StartAtOperationTime != nil) && wireVersion.Max >= 7 { opTime := cs.options.StartAtOperationTime if cs.operationTime != nil { opTime = cs.sess.OperationTime } cs.options.SetStartAtOperationTime(opTime) cs.options.SetResumeAfter(nil) cs.options.SetStartAfter(nil) return } // No cached resume token or operation time: set none of the resume options cs.options.SetResumeAfter(nil) cs.options.SetStartAfter(nil) cs.options.SetStartAtOperationTime(nil) } // ID returns the ID for this change stream, or 0 if the cursor has been closed or exhausted. func (cs ChangeStream) ID() int64 { if cs.cursor == nil { return 0 } return cs.cursor.ID() } // 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 (cs ChangeStream) SetBatchSize(size int32) { // Set batch size on the cursor options also so any "resumed" change stream // cursors will pick up the latest batch size setting. cs.cursorOptions.BatchSize = size cs.cursor.SetBatchSize(size) } // 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 (cs ChangeStream) Decode(val interface{}) error { if cs.cursor == nil { return ErrNilCursor } dec, err := getDecoder(cs.Current, cs.bsonOpts, cs.registry) if err != nil { return fmt.Errorf("error configuring BSON decoder: %w", err) } return dec.Decode(val) } // Err returns the last error seen by the change stream, or nil if no errors has occurred. func (cs ChangeStream) Err() error { if cs.err != nil { return replaceErrors(cs.err) } if cs.cursor == nil { return nil } return replaceErrors(cs.cursor.Err()) } // 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 (cs ChangeStream) Close(ctx context.Context) error { if ctx == nil { ctx = context.Background() } defer closeImplicitSession(cs.sess) if cs.cursor == nil { return nil // cursor is already closed } cs.err = replaceErrors(cs.cursor.Close(ctx)) cs.cursor = nil return cs.Err() } // ResumeToken returns the last cached resume token for this change stream, or nil if a resume token has not been // stored. func (cs ChangeStream) ResumeToken() bson.Raw { return cs.resumeToken } // 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. func (cs ChangeStream) Next(ctx context.Context) bool { return cs.next(ctx, false) } // 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(). // // 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. func (cs ChangeStream) TryNext(ctx context.Context) bool { return cs.next(ctx, true) } func (cs ChangeStream) next(ctx context.Context, nonBlocking bool) bool { // return false right away if the change stream has already errored or if cursor is closed. if cs.err != nil { return false } if ctx == nil { ctx = context.Background() } if len(cs.batch) == 0 { cs.loopNext(ctx, nonBlocking) if cs.err != nil { cs.err = replaceErrors(cs.err) return false } if len(cs.batch) == 0 { return false } } // successfully got non-empty batch cs.Current = bson.Raw(cs.batch[0]) cs.batch = cs.batch[1:] if cs.err = cs.storeResumeToken(); cs.err != nil { return false } return true } func (cs ChangeStream) loopNext(ctx context.Context, nonBlocking bool) { for { if cs.cursor == nil { return } if cs.cursor.Next(ctx) { // non-empty batch returned cs.batch, cs.err = cs.cursor.Batch().Documents() return } cs.err = replaceErrors(cs.cursor.Err()) if cs.err == nil { // Check if cursor is alive if cs.ID() == 0 { return } // If a getMore was done but the batch was empty, the batch cursor will return false with no error. // Update the tracked resume token to catch the post batch resume token from the server response. cs.updatePbrtFromCommand() if nonBlocking { // stop after a successful getMore, even though the batch was empty return } continue // loop getMore until a non-empty batch is returned or an error occurs } if !cs.isResumableError() { return } // ignore error from cursor close because if the cursor is deleted or errors we tried to close it and will remake and try to get next batch _ = cs.cursor.Close(ctx) if cs.err = cs.executeOperation(ctx, true); cs.err != nil { return } } } func (cs ChangeStream) isResumableError() bool { var commandErr CommandError if !errors.As(cs.err, &commandErr) \|\| commandErr.HasErrorLabel(networkErrorLabel) { // All non-server errors or network errors are resumable. return true } if commandErr.Code == errorCursorNotFound { return true } // For wire versions 9 and above, a server error is resumable if it has the ResumableChangeStreamError label. if cs.wireVersion != nil && cs.wireVersion.Includes(minResumableLabelWireVersion) { return commandErr.HasErrorLabel(resumableErrorLabel) } // For wire versions below 9, a server error is resumable if its code is on the allowlist. _, resumable := resumableChangeStreamErrors[commandErr.Code] return resumable } // Returns true if the underlying cursor's batch is empty func (cs *ChangeStream) emptyBatch() bool { return cs.cursor.Batch().Empty() } // StreamType represents the cluster type against which a ChangeStream was created. type StreamType uint8 // 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. const ( CollectionStream StreamType = iota DatabaseStream ClientStream )	22.96 KB	2025-05-25 12:27
📄 change_stream_deployment.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "context" "go.mongodb.org/mongo-driver/mongo/description" "go.mongodb.org/mongo-driver/x/mongo/driver" ) type changeStreamDeployment struct { topologyKind description.TopologyKind server driver.Server conn driver.Connection } var _ driver.Deployment = (changeStreamDeployment)(nil) var _ driver.Server = (changeStreamDeployment)(nil) var _ driver.ErrorProcessor = (changeStreamDeployment)(nil) func (c changeStreamDeployment) SelectServer(context.Context, description.ServerSelector) (driver.Server, error) { return c, nil } func (c changeStreamDeployment) Kind() description.TopologyKind { return c.topologyKind } func (c changeStreamDeployment) Connection(context.Context) (driver.Connection, error) { return c.conn, nil } func (c changeStreamDeployment) RTTMonitor() driver.RTTMonitor { return c.server.RTTMonitor() } func (c changeStreamDeployment) ProcessError(err error, conn driver.Connection) driver.ProcessErrorResult { ep, ok := c.server.(driver.ErrorProcessor) if !ok { return driver.NoChange } return ep.ProcessError(err, conn) }	1.35 KB	2025-05-25 12:27
📄 change_stream_test.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "testing" "go.mongodb.org/mongo-driver/internal/assert" ) func TestChangeStream(t testing.T) { t.Run("nil cursor", func(t testing.T) { cs := &ChangeStream{} id := cs.ID() assert.Equal(t, int64(0), id, "expected ID 0, got %v", id) assert.False(t, cs.Next(bgCtx), "expected Next to return false, got true") err := cs.Decode(nil) assert.Equal(t, ErrNilCursor, err, "expected error %v, got %v", ErrNilCursor, err) err = cs.Err() assert.Nil(t, err, "change stream error: %v", err) err = cs.Close(bgCtx) assert.Nil(t, err, "Close error: %v", err) }) }	869 B	2025-05-25 12:27
📄 client.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "context" "errors" "fmt" "net/http" "time" "go.mongodb.org/mongo-driver/bson" "go.mongodb.org/mongo-driver/bson/bsoncodec" "go.mongodb.org/mongo-driver/event" "go.mongodb.org/mongo-driver/internal/httputil" "go.mongodb.org/mongo-driver/internal/logger" "go.mongodb.org/mongo-driver/internal/uuid" "go.mongodb.org/mongo-driver/mongo/description" "go.mongodb.org/mongo-driver/mongo/options" "go.mongodb.org/mongo-driver/mongo/readconcern" "go.mongodb.org/mongo-driver/mongo/readpref" "go.mongodb.org/mongo-driver/mongo/writeconcern" "go.mongodb.org/mongo-driver/x/bsonx/bsoncore" "go.mongodb.org/mongo-driver/x/mongo/driver" "go.mongodb.org/mongo-driver/x/mongo/driver/mongocrypt" mcopts "go.mongodb.org/mongo-driver/x/mongo/driver/mongocrypt/options" "go.mongodb.org/mongo-driver/x/mongo/driver/operation" "go.mongodb.org/mongo-driver/x/mongo/driver/session" "go.mongodb.org/mongo-driver/x/mongo/driver/topology" ) const ( defaultLocalThreshold = 15 * time.Millisecond defaultMaxPoolSize = 100 ) var ( // keyVaultCollOpts specifies options used to communicate with the key vault collection keyVaultCollOpts = options.Collection().SetReadConcern(readconcern.Majority()). SetWriteConcern(writeconcern.New(writeconcern.WMajority())) endSessionsBatchSize = 10000 ) // 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. type Client struct { id uuid.UUID deployment driver.Deployment localThreshold time.Duration retryWrites bool retryReads bool clock session.ClusterClock readPreference readpref.ReadPref readConcern readconcern.ReadConcern writeConcern writeconcern.WriteConcern bsonOpts options.BSONOptions registry bsoncodec.Registry monitor event.CommandMonitor serverAPI driver.ServerAPIOptions serverMonitor event.ServerMonitor sessionPool session.Pool timeout time.Duration httpClient http.Client logger logger.Logger // client-side encryption fields keyVaultClientFLE Client keyVaultCollFLE Collection mongocryptdFLE mongocryptdClient cryptFLE driver.Crypt metadataClientFLE Client internalClientFLE Client encryptedFieldsMap map[string]interface{} } // Connect creates a new Client and then initializes it using the Connect method. This is equivalent to calling // NewClient followed by Client.Connect. // // 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. func Connect(ctx context.Context, opts ...options.ClientOptions) (Client, error) { c, err := NewClient(opts...) if err != nil { return nil, err } err = c.Connect(ctx) if err != nil { return nil, err } return c, nil } // NewClient creates a new client to connect to a deployment specified by the uri. // // 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. // // Deprecated: Use [Connect] instead. func NewClient(opts ...options.ClientOptions) (Client, error) { clientOpt := options.MergeClientOptions(opts...) id, err := uuid.New() if err != nil { return nil, err } client := &Client{id: id} // ClusterClock client.clock = new(session.ClusterClock) // LocalThreshold client.localThreshold = defaultLocalThreshold if clientOpt.LocalThreshold != nil { client.localThreshold = clientOpt.LocalThreshold } // Monitor if clientOpt.Monitor != nil { client.monitor = clientOpt.Monitor } // ServerMonitor if clientOpt.ServerMonitor != nil { client.serverMonitor = clientOpt.ServerMonitor } // ReadConcern client.readConcern = readconcern.New() if clientOpt.ReadConcern != nil { client.readConcern = clientOpt.ReadConcern } // ReadPreference client.readPreference = readpref.Primary() if clientOpt.ReadPreference != nil { client.readPreference = clientOpt.ReadPreference } // BSONOptions if clientOpt.BSONOptions != nil { client.bsonOpts = clientOpt.BSONOptions } // Registry client.registry = bson.DefaultRegistry if clientOpt.Registry != nil { client.registry = clientOpt.Registry } // RetryWrites client.retryWrites = true // retry writes on by default if clientOpt.RetryWrites != nil { client.retryWrites = clientOpt.RetryWrites } client.retryReads = true if clientOpt.RetryReads != nil { client.retryReads = clientOpt.RetryReads } // Timeout client.timeout = clientOpt.Timeout client.httpClient = clientOpt.HTTPClient // WriteConcern if clientOpt.WriteConcern != nil { client.writeConcern = clientOpt.WriteConcern } // AutoEncryptionOptions if clientOpt.AutoEncryptionOptions != nil { if err := client.configureAutoEncryption(clientOpt); err != nil { return nil, err } } else { client.cryptFLE = clientOpt.Crypt } // Deployment if clientOpt.Deployment != nil { client.deployment = clientOpt.Deployment } // Set default options if clientOpt.MaxPoolSize == nil { clientOpt.SetMaxPoolSize(defaultMaxPoolSize) } if err != nil { return nil, err } cfg, err := topology.NewConfig(clientOpt, client.clock) if err != nil { return nil, err } client.serverAPI = topology.ServerAPIFromServerOptions(cfg.ServerOpts) if client.deployment == nil { client.deployment, err = topology.New(cfg) if err != nil { return nil, replaceErrors(err) } } // Create a logger for the client. client.logger, err = newLogger(clientOpt.LoggerOptions) if err != nil { return nil, fmt.Errorf("invalid logger options: %w", err) } return client, nil } // Connect initializes the Client by starting background monitoring goroutines. // If the Client was created using the NewClient function, this method must be called before a Client can be used. // // Connect starts background goroutines to monitor the state of the deployment and does not do any I/O in the main // goroutine. The Client.Ping method can be used to verify that the connection was created successfully. // // Deprecated: Use [mongo.Connect] instead. func (c Client) Connect(ctx context.Context) error { if connector, ok := c.deployment.(driver.Connector); ok { err := connector.Connect() if err != nil { return replaceErrors(err) } } if c.mongocryptdFLE != nil { if err := c.mongocryptdFLE.connect(ctx); err != nil { return err } } if c.internalClientFLE != nil { if err := c.internalClientFLE.Connect(ctx); err != nil { return err } } if c.keyVaultClientFLE != nil && c.keyVaultClientFLE != c.internalClientFLE && c.keyVaultClientFLE != c { if err := c.keyVaultClientFLE.Connect(ctx); err != nil { return err } } if c.metadataClientFLE != nil && c.metadataClientFLE != c.internalClientFLE && c.metadataClientFLE != c { if err := c.metadataClientFLE.Connect(ctx); err != nil { return err } } var updateChan <-chan description.Topology if subscriber, ok := c.deployment.(driver.Subscriber); ok { sub, err := subscriber.Subscribe() if err != nil { return replaceErrors(err) } updateChan = sub.Updates } c.sessionPool = session.NewPool(updateChan) return nil } // 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 (c Client) Disconnect(ctx context.Context) error { if c.logger != nil { defer c.logger.Close() } if ctx == nil { ctx = context.Background() } if c.httpClient == httputil.DefaultHTTPClient { defer httputil.CloseIdleHTTPConnections(c.httpClient) } c.endSessions(ctx) if c.mongocryptdFLE != nil { if err := c.mongocryptdFLE.disconnect(ctx); err != nil { return err } } if c.internalClientFLE != nil { if err := c.internalClientFLE.Disconnect(ctx); err != nil { return err } } if c.keyVaultClientFLE != nil && c.keyVaultClientFLE != c.internalClientFLE && c.keyVaultClientFLE != c { if err := c.keyVaultClientFLE.Disconnect(ctx); err != nil { return err } } if c.metadataClientFLE != nil && c.metadataClientFLE != c.internalClientFLE && c.metadataClientFLE != c { if err := c.metadataClientFLE.Disconnect(ctx); err != nil { return err } } if c.cryptFLE != nil { c.cryptFLE.Close() } if disconnector, ok := c.deployment.(driver.Disconnector); ok { return replaceErrors(disconnector.Disconnect(ctx)) } return nil } // 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 (c Client) Ping(ctx context.Context, rp readpref.ReadPref) error { if ctx == nil { ctx = context.Background() } if rp == nil { rp = c.readPreference } db := c.Database("admin") res := db.RunCommand(ctx, bson.D{ {"ping", 1}, }, options.RunCmd().SetReadPreference(rp)) return replaceErrors(res.Err()) } // 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. func (c Client) StartSession(opts ...options.SessionOptions) (Session, error) { if c.sessionPool == nil { return nil, ErrClientDisconnected } sopts := options.MergeSessionOptions(opts...) coreOpts := &session.ClientOptions{ DefaultReadConcern: c.readConcern, DefaultReadPreference: c.readPreference, DefaultWriteConcern: c.writeConcern, } if sopts.CausalConsistency != nil { coreOpts.CausalConsistency = sopts.CausalConsistency } if sopts.DefaultReadConcern != nil { coreOpts.DefaultReadConcern = sopts.DefaultReadConcern } if sopts.DefaultWriteConcern != nil { coreOpts.DefaultWriteConcern = sopts.DefaultWriteConcern } if sopts.DefaultReadPreference != nil { coreOpts.DefaultReadPreference = sopts.DefaultReadPreference } if sopts.DefaultMaxCommitTime != nil { coreOpts.DefaultMaxCommitTime = sopts.DefaultMaxCommitTime } if sopts.Snapshot != nil { coreOpts.Snapshot = sopts.Snapshot } sess, err := session.NewClientSession(c.sessionPool, c.id, coreOpts) if err != nil { return nil, replaceErrors(err) } // Writes are not retryable on standalones, so let operation determine whether to retry sess.RetryWrite = false sess.RetryRead = c.retryReads return &sessionImpl{ clientSession: sess, client: c, deployment: c.deployment, }, nil } func (c Client) endSessions(ctx context.Context) { if c.sessionPool == nil { return } sessionIDs := c.sessionPool.IDSlice() op := operation.NewEndSessions(nil).ClusterClock(c.clock).Deployment(c.deployment). ServerSelector(description.ReadPrefSelector(readpref.PrimaryPreferred())).CommandMonitor(c.monitor). Database("admin").Crypt(c.cryptFLE).ServerAPI(c.serverAPI) totalNumIDs := len(sessionIDs) var currentBatch []bsoncore.Document for i := 0; i < totalNumIDs; i++ { currentBatch = append(currentBatch, sessionIDs[i]) // If we are at the end of a batch or the end of the overall IDs array, execute the operation. if ((i+1)%endSessionsBatchSize) == 0 \|\| i == totalNumIDs-1 { // Ignore all errors when ending sessions. _, marshalVal, err := bson.MarshalValue(currentBatch) if err == nil { _ = op.SessionIDs(marshalVal).Execute(ctx) } currentBatch = currentBatch[:0] } } } func (c Client) configureAutoEncryption(clientOpts options.ClientOptions) error { c.encryptedFieldsMap = clientOpts.AutoEncryptionOptions.EncryptedFieldsMap if err := c.configureKeyVaultClientFLE(clientOpts); err != nil { return err } if err := c.configureMetadataClientFLE(clientOpts); err != nil { return err } mc, err := c.newMongoCrypt(clientOpts.AutoEncryptionOptions) if err != nil { return err } // If the crypt_shared library was not loaded, try to spawn and connect to mongocryptd. if mc.CryptSharedLibVersionString() == "" { mongocryptdFLE, err := newMongocryptdClient(clientOpts.AutoEncryptionOptions) if err != nil { return err } c.mongocryptdFLE = mongocryptdFLE } c.configureCryptFLE(mc, clientOpts.AutoEncryptionOptions) return nil } func (c Client) getOrCreateInternalClient(clientOpts options.ClientOptions) (Client, error) { if c.internalClientFLE != nil { return c.internalClientFLE, nil } internalClientOpts := options.MergeClientOptions(clientOpts) internalClientOpts.AutoEncryptionOptions = nil internalClientOpts.SetMinPoolSize(0) var err error c.internalClientFLE, err = NewClient(internalClientOpts) return c.internalClientFLE, err } func (c Client) configureKeyVaultClientFLE(clientOpts options.ClientOptions) error { // parse key vault options and create new key vault client var err error aeOpts := clientOpts.AutoEncryptionOptions switch { case aeOpts.KeyVaultClientOptions != nil: c.keyVaultClientFLE, err = NewClient(aeOpts.KeyVaultClientOptions) case clientOpts.MaxPoolSize != nil && clientOpts.MaxPoolSize == 0: c.keyVaultClientFLE = c default: c.keyVaultClientFLE, err = c.getOrCreateInternalClient(clientOpts) } if err != nil { return err } dbName, collName := splitNamespace(aeOpts.KeyVaultNamespace) c.keyVaultCollFLE = c.keyVaultClientFLE.Database(dbName).Collection(collName, keyVaultCollOpts) return nil } func (c Client) configureMetadataClientFLE(clientOpts options.ClientOptions) error { // parse key vault options and create new key vault client aeOpts := clientOpts.AutoEncryptionOptions if aeOpts.BypassAutoEncryption != nil && aeOpts.BypassAutoEncryption { // no need for a metadata client. return nil } if clientOpts.MaxPoolSize != nil && clientOpts.MaxPoolSize == 0 { c.metadataClientFLE = c return nil } var err error c.metadataClientFLE, err = c.getOrCreateInternalClient(clientOpts) return err } func (c Client) newMongoCrypt(opts options.AutoEncryptionOptions) (mongocrypt.MongoCrypt, error) { // convert schemas in SchemaMap to bsoncore documents cryptSchemaMap := make(map[string]bsoncore.Document) for k, v := range opts.SchemaMap { schema, err := marshal(v, c.bsonOpts, c.registry) if err != nil { return nil, err } cryptSchemaMap[k] = schema } // convert schemas in EncryptedFieldsMap to bsoncore documents cryptEncryptedFieldsMap := make(map[string]bsoncore.Document) for k, v := range opts.EncryptedFieldsMap { encryptedFields, err := marshal(v, c.bsonOpts, c.registry) if err != nil { return nil, err } cryptEncryptedFieldsMap[k] = encryptedFields } kmsProviders, err := marshal(opts.KmsProviders, c.bsonOpts, c.registry) if err != nil { return nil, fmt.Errorf("error creating KMS providers document: %w", err) } // Set the crypt_shared library override path from the "cryptSharedLibPath" extra option if one // was set. cryptSharedLibPath := "" if val, ok := opts.ExtraOptions["cryptSharedLibPath"]; ok { str, ok := val.(string) if !ok { return nil, fmt.Errorf( `expected AutoEncryption extra option "cryptSharedLibPath" to be a string, but is a %T`, val) } cryptSharedLibPath = str } // Explicitly disable loading the crypt_shared library if requested. Note that this is ONLY // intended for use from tests; there is no supported public API for explicitly disabling // loading the crypt_shared library. cryptSharedLibDisabled := false if v, ok := opts.ExtraOptions["__cryptSharedLibDisabledForTestOnly"]; ok { cryptSharedLibDisabled = v.(bool) } bypassAutoEncryption := opts.BypassAutoEncryption != nil && opts.BypassAutoEncryption bypassQueryAnalysis := opts.BypassQueryAnalysis != nil && opts.BypassQueryAnalysis mc, err := mongocrypt.NewMongoCrypt(mcopts.MongoCrypt(). SetKmsProviders(kmsProviders). SetLocalSchemaMap(cryptSchemaMap). SetBypassQueryAnalysis(bypassQueryAnalysis). SetEncryptedFieldsMap(cryptEncryptedFieldsMap). SetCryptSharedLibDisabled(cryptSharedLibDisabled \|\| bypassAutoEncryption). SetCryptSharedLibOverridePath(cryptSharedLibPath). SetHTTPClient(opts.HTTPClient)) if err != nil { return nil, err } var cryptSharedLibRequired bool if val, ok := opts.ExtraOptions["cryptSharedLibRequired"]; ok { b, ok := val.(bool) if !ok { return nil, fmt.Errorf( `expected AutoEncryption extra option "cryptSharedLibRequired" to be a bool, but is a %T`, val) } cryptSharedLibRequired = b } // If the "cryptSharedLibRequired" extra option is set to true, check the MongoCrypt version // string to confirm that the library was successfully loaded. If the version string is empty, // return an error indicating that we couldn't load the crypt_shared library. if cryptSharedLibRequired && mc.CryptSharedLibVersionString() == "" { return nil, errors.New( `AutoEncryption extra option "cryptSharedLibRequired" is true, but we failed to load the crypt_shared library`) } return mc, nil } //nolint:unused // the unused linter thinks that this function is unreachable because "c.newMongoCrypt" always panics without the "cse" build tag set. func (c Client) configureCryptFLE(mc mongocrypt.MongoCrypt, opts options.AutoEncryptionOptions) { bypass := opts.BypassAutoEncryption != nil && opts.BypassAutoEncryption kr := keyRetriever{coll: c.keyVaultCollFLE} var cir collInfoRetriever // If bypass is true, c.metadataClientFLE is nil and the collInfoRetriever // will not be used. If bypass is false, to the parent client or the // internal client. if !bypass { cir = collInfoRetriever{client: c.metadataClientFLE} } c.cryptFLE = driver.NewCrypt(&driver.CryptOptions{ MongoCrypt: mc, CollInfoFn: cir.cryptCollInfo, KeyFn: kr.cryptKeys, MarkFn: c.mongocryptdFLE.markCommand, TLSConfig: opts.TLSConfig, BypassAutoEncryption: bypass, }) } // validSession returns an error if the session doesn't belong to the client func (c Client) validSession(sess session.Client) error { if sess != nil && sess.ClientID != c.id { return ErrWrongClient } return nil } // Database returns a handle for a database with the given name configured with the given DatabaseOptions. func (c Client) Database(name string, opts ...options.DatabaseOptions) Database { return newDatabase(c, name, opts...) } // 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 (c Client) ListDatabases(ctx context.Context, filter interface{}, opts ...options.ListDatabasesOptions) (ListDatabasesResult, error) { if ctx == nil { ctx = context.Background() } sess := sessionFromContext(ctx) err := c.validSession(sess) if err != nil { return ListDatabasesResult{}, err } if sess == nil && c.sessionPool != nil { sess = session.NewImplicitClientSession(c.sessionPool, c.id) defer sess.EndSession() } err = c.validSession(sess) if err != nil { return ListDatabasesResult{}, err } filterDoc, err := marshal(filter, c.bsonOpts, c.registry) if err != nil { return ListDatabasesResult{}, err } selector := description.CompositeSelector([]description.ServerSelector{ description.ReadPrefSelector(readpref.Primary()), description.LatencySelector(c.localThreshold), }) selector = makeReadPrefSelector(sess, selector, c.localThreshold) ldo := options.MergeListDatabasesOptions(opts...) op := operation.NewListDatabases(filterDoc). Session(sess).ReadPreference(c.readPreference).CommandMonitor(c.monitor). ServerSelector(selector).ClusterClock(c.clock).Database("admin").Deployment(c.deployment).Crypt(c.cryptFLE). ServerAPI(c.serverAPI).Timeout(c.timeout) if ldo.NameOnly != nil { op = op.NameOnly(ldo.NameOnly) } if ldo.AuthorizedDatabases != nil { op = op.AuthorizedDatabases(ldo.AuthorizedDatabases) } retry := driver.RetryNone if c.retryReads { retry = driver.RetryOncePerCommand } op.Retry(retry) err = op.Execute(ctx) if err != nil { return ListDatabasesResult{}, replaceErrors(err) } return newListDatabasesResultFromOperation(op.Result()), nil } // 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/. func (c Client) ListDatabaseNames(ctx context.Context, filter interface{}, opts ...options.ListDatabasesOptions) ([]string, error) { opts = append(opts, options.ListDatabases().SetNameOnly(true)) res, err := c.ListDatabases(ctx, filter, opts...) if err != nil { return nil, err } names := make([]string, 0) for _, spec := range res.Databases { names = append(names, spec.Name) } return names, nil } // WithSession creates a new SessionContext from the ctx and sess parameters and uses it to call the fn callback. The // SessionContext must be used as the Context parameter for any operations in the fn callback that should be executed // under the session. // // WithSession is safe to call from multiple goroutines concurrently. However, the SessionContext 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. func WithSession(ctx context.Context, sess Session, fn func(SessionContext) error) error { return fn(NewSessionContext(ctx, sess)) } // UseSession creates a new Session and uses it to create a new SessionContext, which is used to call the fn callback. // The SessionContext parameter must be used as the Context parameter for any operations in the fn callback that should // be executed under a session. 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 SessionContext 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 (c Client) UseSession(ctx context.Context, fn func(SessionContext) error) error { return c.UseSessionWithOptions(ctx, options.Session(), fn) } // UseSessionWithOptions operates like UseSession but uses the given SessionOptions to create the Session. // // UseSessionWithOptions is safe to call from multiple goroutines concurrently. However, the SessionContext passed to // the UseSessionWithOptions callback function is not safe for concurrent use by multiple goroutines. func (c Client) UseSessionWithOptions(ctx context.Context, opts options.SessionOptions, fn func(SessionContext) error) error { defaultSess, err := c.StartSession(opts) if err != nil { return err } defer defaultSess.EndSession(ctx) return fn(NewSessionContext(ctx, defaultSess)) } // 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). func (c Client) Watch(ctx context.Context, pipeline interface{}, opts ...options.ChangeStreamOptions) (ChangeStream, error) { if c.sessionPool == nil { return nil, ErrClientDisconnected } csConfig := changeStreamConfig{ readConcern: c.readConcern, readPreference: c.readPreference, client: c, bsonOpts: c.bsonOpts, registry: c.registry, streamType: ClientStream, crypt: c.cryptFLE, } return newChangeStream(ctx, csConfig, pipeline, opts...) } // 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 (c Client) NumberSessionsInProgress() int { // The underlying session pool uses an int64 for checkedOut to allow atomic // access. We convert to an int here to maintain backward compatibility with // older versions of the driver that did not atomically access checkedOut. return int(c.sessionPool.CheckedOut()) } // Timeout returns the timeout set for this client. func (c Client) Timeout() time.Duration { return c.timeout } func (c Client) createBaseCursorOptions() driver.CursorOptions { return driver.CursorOptions{ CommandMonitor: c.monitor, Crypt: c.cryptFLE, ServerAPI: c.serverAPI, } } // newLogger will use the LoggerOptions to create an internal logger and publish // messages using a LogSink. func newLogger(opts options.LoggerOptions) (logger.Logger, error) { // If there are no logger options, then create a default logger. if opts == nil { opts = options.Logger() } // If there are no component-level options and the environment does not // contain component variables, then do nothing. if (opts.ComponentLevels == nil \|\| len(opts.ComponentLevels) == 0) && !logger.EnvHasComponentVariables() { return nil, nil } // Otherwise, collect the component-level options and create a logger. componentLevels := make(map[logger.Component]logger.Level) for component, level := range opts.ComponentLevels { componentLevels[logger.Component(component)] = logger.Level(level) } return logger.New(opts.Sink, opts.MaxDocumentLength, componentLevels) }	30.05 KB	2025-05-25 12:27
📄 client_encryption.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "context" "errors" "fmt" "strings" "go.mongodb.org/mongo-driver/bson" "go.mongodb.org/mongo-driver/bson/bsonrw" "go.mongodb.org/mongo-driver/bson/primitive" "go.mongodb.org/mongo-driver/mongo/options" "go.mongodb.org/mongo-driver/x/bsonx/bsoncore" "go.mongodb.org/mongo-driver/x/mongo/driver" "go.mongodb.org/mongo-driver/x/mongo/driver/mongocrypt" mcopts "go.mongodb.org/mongo-driver/x/mongo/driver/mongocrypt/options" ) // ClientEncryption is used to create data keys and explicitly encrypt and decrypt BSON values. type ClientEncryption struct { crypt driver.Crypt keyVaultClient Client keyVaultColl Collection } // NewClientEncryption creates a new ClientEncryption instance configured with the given options. func NewClientEncryption(keyVaultClient Client, opts ...options.ClientEncryptionOptions) (ClientEncryption, error) { if keyVaultClient == nil { return nil, errors.New("keyVaultClient must not be nil") } ce := &ClientEncryption{ keyVaultClient: keyVaultClient, } ceo := options.MergeClientEncryptionOptions(opts...) // create keyVaultColl db, coll := splitNamespace(ceo.KeyVaultNamespace) ce.keyVaultColl = ce.keyVaultClient.Database(db).Collection(coll, keyVaultCollOpts) kmsProviders, err := marshal(ceo.KmsProviders, nil, nil) if err != nil { return nil, fmt.Errorf("error creating KMS providers map: %w", err) } mc, err := mongocrypt.NewMongoCrypt(mcopts.MongoCrypt(). SetKmsProviders(kmsProviders). // Explicitly disable loading the crypt_shared library for the Crypt used for // ClientEncryption because it's only needed for AutoEncryption and we don't expect users to // have the crypt_shared library installed if they're using ClientEncryption. SetCryptSharedLibDisabled(true). SetHTTPClient(ceo.HTTPClient)) if err != nil { return nil, err } // create Crypt kr := keyRetriever{coll: ce.keyVaultColl} cir := collInfoRetriever{client: ce.keyVaultClient} ce.crypt = driver.NewCrypt(&driver.CryptOptions{ MongoCrypt: mc, KeyFn: kr.cryptKeys, CollInfoFn: cir.cryptCollInfo, TLSConfig: ceo.TLSConfig, }) return ce, nil } // 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 (ce ClientEncryption) CreateEncryptedCollection(ctx context.Context, db Database, coll string, createOpts options.CreateCollectionOptions, kmsProvider string, masterKey interface{}) (Collection, bson.M, error) { if createOpts == nil { return nil, nil, errors.New("nil CreateCollectionOptions") } ef := createOpts.EncryptedFields if ef == nil { return nil, nil, errors.New("no EncryptedFields defined for the collection") } efBSON, err := marshal(ef, db.bsonOpts, db.registry) if err != nil { return nil, nil, err } r := bsonrw.NewBSONDocumentReader(efBSON) dec, err := bson.NewDecoder(r) if err != nil { return nil, nil, err } var m bson.M err = dec.Decode(&m) if err != nil { return nil, nil, err } if v, ok := m["fields"]; ok { if fields, ok := v.(bson.A); ok { for _, field := range fields { if f, ok := field.(bson.M); !ok { continue } else if v, ok := f["keyId"]; ok && v == nil { dkOpts := options.DataKey() if masterKey != nil { dkOpts.SetMasterKey(masterKey) } keyid, err := ce.CreateDataKey(ctx, kmsProvider, dkOpts) if err != nil { createOpts.EncryptedFields = m return nil, m, err } f["keyId"] = keyid } } createOpts.EncryptedFields = m } } err = db.CreateCollection(ctx, coll, createOpts) if err != nil { return nil, m, err } return db.Collection(coll), m, nil } // 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 (ce ClientEncryption) AddKeyAltName(ctx context.Context, id primitive.Binary, keyAltName string) SingleResult { filter := bsoncore.NewDocumentBuilder().AppendBinary("_id", id.Subtype, id.Data).Build() keyAltNameDoc := bsoncore.NewDocumentBuilder().AppendString("keyAltNames", keyAltName).Build() update := bsoncore.NewDocumentBuilder().AppendDocument("$addToSet", keyAltNameDoc).Build() return ce.keyVaultColl.FindOneAndUpdate(ctx, filter, update) } // 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 (ce ClientEncryption) CreateDataKey(ctx context.Context, kmsProvider string, opts ...options.DataKeyOptions) (primitive.Binary, error) { // translate opts to mcopts.DataKeyOptions dko := options.MergeDataKeyOptions(opts...) co := mcopts.DataKey().SetKeyAltNames(dko.KeyAltNames) if dko.MasterKey != nil { keyDoc, err := marshal( dko.MasterKey, ce.keyVaultClient.bsonOpts, ce.keyVaultClient.registry) if err != nil { return primitive.Binary{}, err } co.SetMasterKey(keyDoc) } if dko.KeyMaterial != nil { co.SetKeyMaterial(dko.KeyMaterial) } // create data key document dataKeyDoc, err := ce.crypt.CreateDataKey(ctx, kmsProvider, co) if err != nil { return primitive.Binary{}, err } // insert key into key vault _, err = ce.keyVaultColl.InsertOne(ctx, dataKeyDoc) if err != nil { return primitive.Binary{}, err } subtype, data := bson.Raw(dataKeyDoc).Lookup("_id").Binary() return primitive.Binary{Subtype: subtype, Data: data}, nil } // transformExplicitEncryptionOptions creates explicit encryption options to be passed to libmongocrypt. func transformExplicitEncryptionOptions(opts ...options.EncryptOptions) mcopts.ExplicitEncryptionOptions { eo := options.MergeEncryptOptions(opts...) transformed := mcopts.ExplicitEncryption() if eo.KeyID != nil { transformed.SetKeyID(eo.KeyID) } if eo.KeyAltName != nil { transformed.SetKeyAltName(eo.KeyAltName) } transformed.SetAlgorithm(eo.Algorithm) transformed.SetQueryType(eo.QueryType) if eo.ContentionFactor != nil { transformed.SetContentionFactor(eo.ContentionFactor) } if eo.RangeOptions != nil { var transformedRange mcopts.ExplicitRangeOptions if eo.RangeOptions.Min != nil { transformedRange.Min = &bsoncore.Value{Type: eo.RangeOptions.Min.Type, Data: eo.RangeOptions.Min.Value} } if eo.RangeOptions.Max != nil { transformedRange.Max = &bsoncore.Value{Type: eo.RangeOptions.Max.Type, Data: eo.RangeOptions.Max.Value} } if eo.RangeOptions.Precision != nil { transformedRange.Precision = eo.RangeOptions.Precision } transformedRange.Sparsity = eo.RangeOptions.Sparsity transformed.SetRangeOptions(transformedRange) } return transformed } // Encrypt encrypts a BSON value with the given key and algorithm. Returns an encrypted value (BSON binary of subtype 6). func (ce ClientEncryption) Encrypt(ctx context.Context, val bson.RawValue, opts ...options.EncryptOptions) (primitive.Binary, error) { transformed := transformExplicitEncryptionOptions(opts...) subtype, data, err := ce.crypt.EncryptExplicit(ctx, bsoncore.Value{Type: val.Type, Data: val.Value}, transformed) if err != nil { return primitive.Binary{}, err } return primitive.Binary{Subtype: subtype, Data: data}, nil } // 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 "rangePreview" // Beta: The Range algorithm is experimental only. It is not intended for public use. It is subject to breaking changes. func (ce ClientEncryption) EncryptExpression(ctx context.Context, expr interface{}, result interface{}, opts ...options.EncryptOptions) error { transformed := transformExplicitEncryptionOptions(opts...) exprDoc, err := marshal(expr, nil, nil) if err != nil { return err } encryptedExprDoc, err := ce.crypt.EncryptExplicitExpression(ctx, exprDoc, transformed) if err != nil { return err } if raw, ok := result.(bson.Raw); ok { // Avoid the cost of Unmarshal. raw = bson.Raw(encryptedExprDoc) return nil } err = bson.Unmarshal([]byte(encryptedExprDoc), result) if err != nil { return err } return nil } // Decrypt decrypts an encrypted value (BSON binary of subtype 6) and returns the original BSON value. func (ce ClientEncryption) Decrypt(ctx context.Context, val primitive.Binary) (bson.RawValue, error) { decrypted, err := ce.crypt.DecryptExplicit(ctx, val.Subtype, val.Data) if err != nil { return bson.RawValue{}, err } return bson.RawValue{Type: decrypted.Type, Value: decrypted.Data}, nil } // Close cleans up any resources associated with the ClientEncryption instance. This includes disconnecting the // key-vault Client instance. func (ce ClientEncryption) Close(ctx context.Context) error { ce.crypt.Close() return ce.keyVaultClient.Disconnect(ctx) } // 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 (ce ClientEncryption) DeleteKey(ctx context.Context, id primitive.Binary) (DeleteResult, error) { filter := bsoncore.NewDocumentBuilder().AppendBinary("_id", id.Subtype, id.Data).Build() return ce.keyVaultColl.DeleteOne(ctx, filter) } // GetKeyByAltName returns a key document in the key vault collection with the given keyAltName. func (ce ClientEncryption) GetKeyByAltName(ctx context.Context, keyAltName string) SingleResult { filter := bsoncore.NewDocumentBuilder().AppendString("keyAltNames", keyAltName).Build() return ce.keyVaultColl.FindOne(ctx, filter) } // 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 (ce ClientEncryption) GetKey(ctx context.Context, id primitive.Binary) SingleResult { filter := bsoncore.NewDocumentBuilder().AppendBinary("_id", id.Subtype, id.Data).Build() return ce.keyVaultColl.FindOne(ctx, filter) } // GetKeys finds all documents in the key vault collection. Returns the result of the internal find() operation on the // key vault collection. func (ce ClientEncryption) GetKeys(ctx context.Context) (Cursor, error) { return ce.keyVaultColl.Find(ctx, bson.D{}) } // 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 (ce ClientEncryption) RemoveKeyAltName(ctx context.Context, id primitive.Binary, keyAltName string) SingleResult { filter := bsoncore.NewDocumentBuilder().AppendBinary("_id", id.Subtype, id.Data).Build() update := bson.A{bson.D{{"$set", bson.D{{"keyAltNames", bson.D{{"$cond", bson.A{bson.D{{"$eq", bson.A{"$keyAltNames", bson.A{keyAltName}}}}, "$$REMOVE", bson.D{{"$filter", bson.D{{"input", "$keyAltNames"}, {"cond", bson.D{{"$ne", bson.A{"$$this", keyAltName}}}}}}}}}}}}}}} return ce.keyVaultColl.FindOneAndUpdate(ctx, filter, update) } // setRewrapManyDataKeyWriteModels will prepare the WriteModel slice for a bulk updating rewrapped documents. func setRewrapManyDataKeyWriteModels(rewrappedDocuments []bsoncore.Document, writeModels []WriteModel) error { const idKey = "_id" const keyMaterial = "keyMaterial" const masterKey = "masterKey" if writeModels == nil { return fmt.Errorf("writeModels pointer not set for location referenced") } // Append a slice of WriteModel with the update document per each rewrappedDoc _id filter. for _, rewrappedDocument := range rewrappedDocuments { // Prepare the new master key for update. masterKeyValue, err := rewrappedDocument.LookupErr(masterKey) if err != nil { return err } masterKeyDoc := masterKeyValue.Document() // Prepare the new material key for update. keyMaterialValue, err := rewrappedDocument.LookupErr(keyMaterial) if err != nil { return err } keyMaterialSubtype, keyMaterialData := keyMaterialValue.Binary() keyMaterialBinary := primitive.Binary{Subtype: keyMaterialSubtype, Data: keyMaterialData} // Prepare the _id filter for documents to update. id, err := rewrappedDocument.LookupErr(idKey) if err != nil { return err } idSubtype, idData, ok := id.BinaryOK() if !ok { return fmt.Errorf("expected to assert %q as binary, got type %T", idKey, id) } binaryID := primitive.Binary{Subtype: idSubtype, Data: idData} // Append the mutable document to the slice for bulk update. writeModels = append(writeModels, NewUpdateOneModel(). SetFilter(bson.D{{idKey, binaryID}}). SetUpdate( bson.D{ {"$set", bson.D{{keyMaterial, keyMaterialBinary}, {masterKey, masterKeyDoc}}}, {"$currentDate", bson.D{{"updateDate", true}}}, }, )) } return nil } // 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. func (ce ClientEncryption) RewrapManyDataKey(ctx context.Context, filter interface{}, opts ...options.RewrapManyDataKeyOptions) (RewrapManyDataKeyResult, error) { // libmongocrypt versions 1.5.0 and 1.5.1 have a severe bug in RewrapManyDataKey. // Check if the version string starts with 1.5.0 or 1.5.1. This accounts for pre-release versions, like 1.5.0-rc0. libmongocryptVersion := mongocrypt.Version() if strings.HasPrefix(libmongocryptVersion, "1.5.0") \|\| strings.HasPrefix(libmongocryptVersion, "1.5.1") { return nil, fmt.Errorf("RewrapManyDataKey requires libmongocrypt 1.5.2 or newer. Detected version: %v", libmongocryptVersion) } rmdko := options.MergeRewrapManyDataKeyOptions(opts...) if ctx == nil { ctx = context.Background() } // Transfer rmdko options to /x/ package options to publish the mongocrypt feed. co := mcopts.RewrapManyDataKey() if rmdko.MasterKey != nil { keyDoc, err := marshal( rmdko.MasterKey, ce.keyVaultClient.bsonOpts, ce.keyVaultClient.registry) if err != nil { return nil, err } co.SetMasterKey(keyDoc) } if rmdko.Provider != nil { co.SetProvider(*rmdko.Provider) } // Prepare the filters and rewrap the data key using mongocrypt. filterdoc, err := marshal(filter, ce.keyVaultClient.bsonOpts, ce.keyVaultClient.registry) if err != nil { return nil, err } rewrappedDocuments, err := ce.crypt.RewrapDataKey(ctx, filterdoc, co) if err != nil { return nil, err } if len(rewrappedDocuments) == 0 { // If there are no documents to rewrap, then do nothing. return new(RewrapManyDataKeyResult), nil } // Prepare the WriteModel slice for bulk updating the rewrapped data keys. models := []WriteModel{} if err := setRewrapManyDataKeyWriteModels(rewrappedDocuments, &models); err != nil { return nil, err } bulkWriteResults, err := ce.keyVaultColl.BulkWrite(ctx, models) return &RewrapManyDataKeyResult{BulkWriteResult: bulkWriteResults}, err } // splitNamespace takes a namespace in the form "database.collection" and returns (database name, collection name) func splitNamespace(ns string) (string, string) { firstDot := strings.Index(ns, ".") if firstDot == -1 { return "", ns } return ns[:firstDot], ns[firstDot+1:] }	15.86 KB	2025-05-25 12:27
📄 client_examples_test.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo_test import ( "context" "fmt" "log" "go.mongodb.org/mongo-driver/bson" "go.mongodb.org/mongo-driver/mongo" "go.mongodb.org/mongo-driver/mongo/options" "go.mongodb.org/mongo-driver/mongo/readpref" ) func ExampleClient() { // Create a Client and execute a ListDatabases operation. client, err := mongo.Connect( context.TODO(), options.Client().ApplyURI("mongodb://localhost:27017")) if err != nil { log.Fatal(err) } defer func() { if err = client.Disconnect(context.TODO()); err != nil { log.Fatal(err) } }() collection := client.Database("db").Collection("coll") result, err := collection.InsertOne(context.TODO(), bson.D{{"x", 1}}) if err != nil { log.Fatal(err) } fmt.Printf("inserted ID: %v\n", result.InsertedID) } func ExampleConnect_ping() { // 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(context.TODO(), clientOpts) if err != nil { log.Fatal(err) } defer func() { if err = client.Disconnect(context.TODO()); err != nil { log.Fatal(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.Fatal(err) } } func ExampleConnect_replicaSet() { // 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(context.TODO(), clientOpts) if err != nil { log.Fatal(err) } _ = client } func ExampleConnect_sharded() { // 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(context.TODO(), clientOpts) if err != nil { log.Fatal(err) } _ = client } func ExampleConnect_sRV() { // 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(context.TODO(), clientOpts) if err != nil { log.Fatal(err) } _ = client } func ExampleConnect_direct() { // 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(context.TODO(), clientOpts) if err != nil { log.Fatal(err) } _ = client } func ExampleConnect_sCRAM() { // 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(context.TODO(), clientOpts) if err != nil { log.Fatal(err) } _ = client } func ExampleConnect_x509() { // 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(context.TODO(), clientOpts) if err != nil { log.Fatal(err) } _ = client } func ExampleConnect_pLAIN() { // 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(context.TODO(), clientOpts) if err != nil { log.Fatal(err) } _ = client } func ExampleConnect_kerberos() { // 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(context.TODO(), clientOpts) if err != nil { log.Fatal(err) } _ = client } func ExampleConnect_aWS() { // 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( context.TODO(), 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( context.TODO(), 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( context.TODO(), 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( context.TODO(), options.Client().SetAuth(ecCredential)) if err != nil { panic(err) } _ = ecClient } func ExampleConnect_stableAPI() { // 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( context.TODO(), 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( context.TODO(), 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{}) 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( context.TODO(), options.Client().SetServerAPIOptions(serverAPIDeprecation)) if err != nil { panic(err) } _ = serverAPIDeprecationClient } func ExampleConnect_bSONOptions() { // 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(context.TODO(), 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) } }	16.3 KB	2025-05-25 12:27
📄 client_side_encryption_examples_test.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "context" "crypto/rand" "encoding/base64" "fmt" "log" "go.mongodb.org/mongo-driver/bson" "go.mongodb.org/mongo-driver/bson/primitive" "go.mongodb.org/mongo-driver/mongo/options" ) func 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.Fatal(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(context.TODO(), clientOpts) if err != nil { log.Fatalf("Connect error: %v", err) } defer func() { if err = client.Disconnect(context.TODO()); err != nil { log.Fatalf("Disconnect error: %v", err) } }() collection := client.Database("test").Collection("coll") if err := collection.Drop(context.TODO()); err != nil { log.Fatalf("Collection.Drop error: %v", err) } _, err = collection.InsertOne( context.TODO(), bson.D{{"encryptedField", "123456789"}}) if err != nil { log.Fatalf("InsertOne error: %v", err) } res, err := collection.FindOne(context.TODO(), bson.D{}).Raw() if err != nil { log.Fatalf("FindOne error: %v", err) } fmt.Println(res) } func 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( context.TODO(), options.Client().ApplyURI(uri)) if err != nil { log.Fatalf("Connect error for keyVaultClient: %v", err) } clientEnc, err := NewClientEncryption(keyVaultClient, clientEncryptionOpts) if err != nil { log.Fatalf("NewClientEncryption error: %v", err) } defer func() { // this will disconnect the keyVaultClient as well if err = clientEnc.Close(context.TODO()); err != nil { log.Fatalf("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.Fatalf("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.Fatalf("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(context.TODO(), clientOptions) if err != nil { log.Fatalf("Connect error for encrypted client: %v", err) } defer func() { _ = client.Disconnect(context.TODO()) }() // Use client for operations. } func 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. client, err := Connect( context.TODO(), options.Client().ApplyURI("mongodb://localhost:27017")) 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"].(primitive.Binary)) if err != nil { panic(err) } fmt.Printf("Decrypted value: %s\n", decrypted) } func 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(context.TODO(), 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) }	11.11 KB	2025-05-25 12:27
📄 client_test.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "context" "errors" "math" "os" "testing" "time" "go.mongodb.org/mongo-driver/bson" "go.mongodb.org/mongo-driver/event" "go.mongodb.org/mongo-driver/internal/assert" "go.mongodb.org/mongo-driver/internal/integtest" "go.mongodb.org/mongo-driver/mongo/options" "go.mongodb.org/mongo-driver/mongo/readconcern" "go.mongodb.org/mongo-driver/mongo/readpref" "go.mongodb.org/mongo-driver/mongo/writeconcern" "go.mongodb.org/mongo-driver/tag" "go.mongodb.org/mongo-driver/x/mongo/driver/mongocrypt" "go.mongodb.org/mongo-driver/x/mongo/driver/session" "go.mongodb.org/mongo-driver/x/mongo/driver/topology" ) var bgCtx = context.Background() func setupClient(opts ...options.ClientOptions) Client { if len(opts) == 0 { clientOpts := options.Client().ApplyURI("mongodb://localhost:27017") integtest.AddTestServerAPIVersion(clientOpts) opts = append(opts, clientOpts) } client, _ := NewClient(opts...) return client } func TestClient(t testing.T) { t.Run("new client", func(t testing.T) { client := setupClient() assert.NotNil(t, client.deployment, "expected valid deployment, got nil") }) t.Run("database", func(t testing.T) { dbName := "foo" client := setupClient() db := client.Database(dbName) assert.Equal(t, dbName, db.Name(), "expected db name %v, got %v", dbName, db.Name()) assert.Equal(t, client, db.Client(), "expected client %v, got %v", client, db.Client()) }) t.Run("replace topology error", func(t testing.T) { client := setupClient() _, err := client.StartSession() assert.Equal(t, ErrClientDisconnected, err, "expected error %v, got %v", ErrClientDisconnected, err) _, err = client.ListDatabases(bgCtx, bson.D{}) assert.Equal(t, ErrClientDisconnected, err, "expected error %v, got %v", ErrClientDisconnected, err) err = client.Ping(bgCtx, nil) assert.Equal(t, ErrClientDisconnected, err, "expected error %v, got %v", ErrClientDisconnected, err) err = client.Disconnect(bgCtx) assert.Equal(t, ErrClientDisconnected, err, "expected error %v, got %v", ErrClientDisconnected, err) _, err = client.Watch(bgCtx, []bson.D{}) assert.Equal(t, ErrClientDisconnected, err, "expected error %v, got %v", ErrClientDisconnected, err) }) t.Run("nil document error", func(t testing.T) { // manually set session pool to non-nil because Watch will return ErrClientDisconnected client := setupClient() client.sessionPool = &session.Pool{} _, err := client.Watch(bgCtx, nil) watchErr := errors.New("can only marshal slices and arrays into aggregation pipelines, but got invalid") assert.Equal(t, watchErr, err, "expected error %v, got %v", watchErr, err) _, err = client.ListDatabases(bgCtx, nil) assert.Equal(t, ErrNilDocument, err, "expected error %v, got %v", ErrNilDocument, err) _, err = client.ListDatabaseNames(bgCtx, nil) assert.Equal(t, ErrNilDocument, err, "expected error %v, got %v", ErrNilDocument, err) }) t.Run("read preference", func(t testing.T) { t.Run("absent", func(t testing.T) { client := setupClient() gotMode := client.readPreference.Mode() wantMode := readpref.PrimaryMode assert.Equal(t, gotMode, wantMode, "expected mode %v, got %v", wantMode, gotMode) _, flag := client.readPreference.MaxStaleness() assert.False(t, flag, "expected max staleness to not be set but was") }) t.Run("specified", func(t testing.T) { tags := []tag.Set{ { tag.Tag{ Name: "one", Value: "1", }, }, { tag.Tag{ Name: "two", Value: "2", }, }, } cs := "mongodb://localhost:27017/" cs += "?readpreference=secondary&readPreferenceTags=one:1&readPreferenceTags=two:2&maxStaleness=5" client := setupClient(options.Client().ApplyURI(cs)) gotMode := client.readPreference.Mode() assert.Equal(t, gotMode, readpref.SecondaryMode, "expected mode %v, got %v", readpref.SecondaryMode, gotMode) gotTags := client.readPreference.TagSets() assert.Equal(t, gotTags, tags, "expected tags %v, got %v", tags, gotTags) gotStaleness, flag := client.readPreference.MaxStaleness() assert.True(t, flag, "expected max staleness to be set but was not") wantStaleness := time.Duration(5) * time.Second assert.Equal(t, gotStaleness, wantStaleness, "expected staleness %v, got %v", wantStaleness, gotStaleness) }) }) t.Run("localThreshold", func(t testing.T) { testCases := []struct { name string opts options.ClientOptions expectedThreshold time.Duration }{ {"default", options.Client(), defaultLocalThreshold}, {"custom", options.Client().SetLocalThreshold(10 * time.Second), 10 * time.Second}, } for _, tc := range testCases { t.Run(tc.name, func(t testing.T) { client := setupClient(tc.opts) assert.Equal(t, tc.expectedThreshold, client.localThreshold, "expected localThreshold %v, got %v", tc.expectedThreshold, client.localThreshold) }) } }) t.Run("read concern", func(t testing.T) { rc := readconcern.Majority() client := setupClient(options.Client().SetReadConcern(rc)) assert.Equal(t, rc, client.readConcern, "expected read concern %v, got %v", rc, client.readConcern) }) t.Run("min pool size from SetPoolSize()", func(t testing.T) { testCases := []struct { name string opts options.ClientOptions err error }{ { name: "minPoolSize < default maxPoolSize", opts: options.Client().SetMinPoolSize(64), err: nil, }, { name: "minPoolSize > default maxPoolSize", opts: options.Client().SetMinPoolSize(128), err: errors.New("minPoolSize must be less than or equal to maxPoolSize, got minPoolSize=128 maxPoolSize=100"), }, { name: "minPoolSize < maxPoolSize", opts: options.Client().SetMinPoolSize(128).SetMaxPoolSize(256), err: nil, }, { name: "minPoolSize == maxPoolSize", opts: options.Client().SetMinPoolSize(128).SetMaxPoolSize(128), err: nil, }, { name: "minPoolSize > maxPoolSize", opts: options.Client().SetMinPoolSize(64).SetMaxPoolSize(32), err: errors.New("minPoolSize must be less than or equal to maxPoolSize, got minPoolSize=64 maxPoolSize=32"), }, { name: "maxPoolSize == 0", opts: options.Client().SetMinPoolSize(128).SetMaxPoolSize(0), err: nil, }, } for _, tc := range testCases { t.Run(tc.name, func(t testing.T) { _, err := NewClient(tc.opts) assert.Equal(t, tc.err, err, "expected error %v, got %v", tc.err, err) }) } }) t.Run("min pool size from ApplyURI()", func(t testing.T) { testCases := []struct { name string opts options.ClientOptions err error }{ { name: "minPoolSize < default maxPoolSize", opts: options.Client().ApplyURI("mongodb://localhost:27017/?minPoolSize=64"), err: nil, }, { name: "minPoolSize > default maxPoolSize", opts: options.Client().ApplyURI("mongodb://localhost:27017/?minPoolSize=128"), err: errors.New("minPoolSize must be less than or equal to maxPoolSize, got minPoolSize=128 maxPoolSize=100"), }, { name: "minPoolSize < maxPoolSize", opts: options.Client().ApplyURI("mongodb://localhost:27017/?minPoolSize=128&maxPoolSize=256"), err: nil, }, { name: "minPoolSize == maxPoolSize", opts: options.Client().ApplyURI("mongodb://localhost:27017/?minPoolSize=128&maxPoolSize=128"), err: nil, }, { name: "minPoolSize > maxPoolSize", opts: options.Client().ApplyURI("mongodb://localhost:27017/?minPoolSize=64&maxPoolSize=32"), err: errors.New("minPoolSize must be less than or equal to maxPoolSize, got minPoolSize=64 maxPoolSize=32"), }, { name: "maxPoolSize == 0", opts: options.Client().ApplyURI("mongodb://localhost:27017/?minPoolSize=128&maxPoolSize=0"), err: nil, }, } for _, tc := range testCases { t.Run(tc.name, func(t testing.T) { _, err := NewClient(tc.opts) assert.Equal(t, tc.err, err, "expected error %v, got %v", tc.err, err) }) } }) t.Run("retry writes", func(t testing.T) { retryWritesURI := "mongodb://localhost:27017/?retryWrites=false" retryWritesErrorURI := "mongodb://localhost:27017/?retryWrites=foobar" testCases := []struct { name string opts options.ClientOptions expectErr bool expectedRetry bool }{ {"default", options.Client(), false, true}, {"custom options", options.Client().SetRetryWrites(false), false, false}, {"custom URI", options.Client().ApplyURI(retryWritesURI), false, false}, {"custom URI error", options.Client().ApplyURI(retryWritesErrorURI), true, false}, } for _, tc := range testCases { t.Run(tc.name, func(t testing.T) { client, err := NewClient(tc.opts) if tc.expectErr { assert.NotNil(t, err, "expected error, got nil") return } assert.Nil(t, err, "configuration error: %v", err) assert.Equal(t, tc.expectedRetry, client.retryWrites, "expected retryWrites %v, got %v", tc.expectedRetry, client.retryWrites) }) } }) t.Run("retry reads", func(t testing.T) { retryReadsURI := "mongodb://localhost:27017/?retryReads=false" retryReadsErrorURI := "mongodb://localhost:27017/?retryReads=foobar" testCases := []struct { name string opts options.ClientOptions expectErr bool expectedRetry bool }{ {"default", options.Client(), false, true}, {"custom options", options.Client().SetRetryReads(false), false, false}, {"custom URI", options.Client().ApplyURI(retryReadsURI), false, false}, {"custom URI error", options.Client().ApplyURI(retryReadsErrorURI), true, false}, } for _, tc := range testCases { t.Run(tc.name, func(t testing.T) { client, err := NewClient(tc.opts) if tc.expectErr { assert.NotNil(t, err, "expected error, got nil") return } assert.Nil(t, err, "configuration error: %v", err) assert.Equal(t, tc.expectedRetry, client.retryReads, "expected retryReads %v, got %v", tc.expectedRetry, client.retryReads) }) } }) t.Run("write concern", func(t testing.T) { wc := writeconcern.New(writeconcern.WMajority()) client := setupClient(options.Client().SetWriteConcern(wc)) assert.Equal(t, wc, client.writeConcern, "mismatch; expected write concern %v, got %v", wc, client.writeConcern) }) t.Run("server monitor", func(t testing.T) { monitor := &event.ServerMonitor{} client := setupClient(options.Client().SetServerMonitor(monitor)) assert.Equal(t, monitor, client.serverMonitor, "expected sdam monitor %v, got %v", monitor, client.serverMonitor) }) t.Run("GetURI", func(t testing.T) { t.Run("ApplyURI not called", func(t testing.T) { opts := options.Client().SetHosts([]string{"localhost:27017"}) uri := opts.GetURI() assert.Equal(t, "", uri, "expected GetURI to return empty string, got %v", uri) }) t.Run("ApplyURI called with empty string", func(t testing.T) { opts := options.Client().ApplyURI("") uri := opts.GetURI() assert.Equal(t, "", uri, "expected GetURI to return empty string, got %v", uri) }) t.Run("ApplyURI called with non-empty string", func(t testing.T) { uri := "mongodb://localhost:27017/foobar" opts := options.Client().ApplyURI(uri) got := opts.GetURI() assert.Equal(t, uri, got, "expected GetURI to return %v, got %v", uri, got) }) }) t.Run("endSessions", func(t testing.T) { cs := integtest.ConnString(t) originalBatchSize := endSessionsBatchSize endSessionsBatchSize = 2 defer func() { endSessionsBatchSize = originalBatchSize }() testCases := []struct { name string numSessions int eventBatchSizes []int }{ {"number of sessions divides evenly", endSessionsBatchSize * 2, []int{endSessionsBatchSize, endSessionsBatchSize}}, {"number of sessions does not divide evenly", endSessionsBatchSize + 1, []int{endSessionsBatchSize, 1}}, } for _, tc := range testCases { if testing.Short() { t.Skip("skipping integration test in short mode") } if os.Getenv("DOCKER_RUNNING") != "" { t.Skip("skipping test in docker environment") } t.Run(tc.name, func(t testing.T) { // Setup a client and skip the test based on server version. var started []event.CommandStartedEvent var failureReasons []string cmdMonitor := &event.CommandMonitor{ Started: func(_ context.Context, evt event.CommandStartedEvent) { if evt.CommandName == "endSessions" { started = append(started, evt) } }, Failed: func(_ context.Context, evt event.CommandFailedEvent) { if evt.CommandName == "endSessions" { failureReasons = append(failureReasons, evt.Failure) } }, } clientOpts := options.Client().ApplyURI(cs.Original).SetReadPreference(readpref.Primary()). SetWriteConcern(writeconcern.New(writeconcern.WMajority())).SetMonitor(cmdMonitor) integtest.AddTestServerAPIVersion(clientOpts) client, err := Connect(bgCtx, clientOpts) assert.Nil(t, err, "Connect error: %v", err) defer func() { _ = client.Disconnect(bgCtx) }() serverVersion, err := getServerVersion(client.Database("admin")) assert.Nil(t, err, "getServerVersion error: %v", err) if compareVersions(serverVersion, "3.6.0") < 1 { t.Skip("skipping server version < 3.6") } coll := client.Database("foo").Collection("bar") defer func() { _ = coll.Drop(bgCtx) }() // Do an application operation and create the number of sessions specified by the test. _, err = coll.CountDocuments(bgCtx, bson.D{}) assert.Nil(t, err, "CountDocuments error: %v", err) var sessions []Session for i := 0; i < tc.numSessions; i++ { sess, err := client.StartSession() assert.Nil(t, err, "StartSession error at index %d: %v", i, err) sessions = append(sessions, sess) } for _, sess := range sessions { sess.EndSession(bgCtx) } client.endSessions(bgCtx) divisionResult := float64(tc.numSessions) / float64(endSessionsBatchSize) numEventsExpected := int(math.Ceil(divisionResult)) assert.Equal(t, len(started), numEventsExpected, "expected %d started events, got %d", numEventsExpected, len(started)) assert.Equal(t, len(failureReasons), 0, "endSessions errors: %v", failureReasons) for i := 0; i < numEventsExpected; i++ { sentArray := started[i].Command.Lookup("endSessions").Array() values, _ := sentArray.Values() expectedNumValues := tc.eventBatchSizes[i] assert.Equal(t, len(values), expectedNumValues, "batch size mismatch at index %d; expected %d sessions in batch, got %d", i, expectedNumValues, len(values)) } }) } }) t.Run("serverAPI version", func(t testing.T) { getServerAPIOptions := func() options.ServerAPIOptions { return options.ServerAPI(options.ServerAPIVersion1). SetStrict(false).SetDeprecationErrors(false) } t.Run("success with all options", func(t testing.T) { serverAPIOptions := getServerAPIOptions() client, err := NewClient(options.Client().SetServerAPIOptions(serverAPIOptions)) assert.Nil(t, err, "unexpected error from NewClient: %v", err) convertedAPIOptions := topology.ConvertToDriverAPIOptions(serverAPIOptions) assert.Equal(t, convertedAPIOptions, client.serverAPI, "mismatch in serverAPI; expected %v, got %v", convertedAPIOptions, client.serverAPI) }) t.Run("failure with unsupported version", func(t testing.T) { serverAPIOptions := options.ServerAPI("badVersion") _, err := NewClient(options.Client().SetServerAPIOptions(serverAPIOptions)) assert.NotNil(t, err, "expected error from NewClient, got nil") errmsg := `api version "badVersion" not supported; this driver version only supports API version "1"` assert.Equal(t, errmsg, err.Error(), "expected error %v, got %v", errmsg, err.Error()) }) t.Run("cannot modify options after client creation", func(t testing.T) { serverAPIOptions := getServerAPIOptions() client, err := NewClient(options.Client().SetServerAPIOptions(serverAPIOptions)) assert.Nil(t, err, "unexpected error from NewClient: %v", err) expectedServerAPIOptions := getServerAPIOptions() // modify passed-in options serverAPIOptions.SetStrict(true).SetDeprecationErrors(true) convertedAPIOptions := topology.ConvertToDriverAPIOptions(expectedServerAPIOptions) assert.Equal(t, convertedAPIOptions, client.serverAPI, "unexpected modification to serverAPI; expected %v, got %v", convertedAPIOptions, client.serverAPI) }) }) t.Run("mongocryptd or crypt_shared", func(t testing.T) { cryptSharedLibPath := os.Getenv("CRYPT_SHARED_LIB_PATH") if cryptSharedLibPath == "" { t.Skip("CRYPT_SHARED_LIB_PATH not set, skipping") } if len(mongocrypt.Version()) == 0 { t.Skip("Not built with cse flag") } testCases := []struct { description string useCryptSharedLib bool }{ { description: "when crypt_shared is loaded, should not attempt to spawn mongocryptd", useCryptSharedLib: true, }, { description: "when crypt_shared is not loaded, should attempt to spawn mongocryptd", useCryptSharedLib: false, }, } for _, tc := range testCases { t.Run(tc.description, func(t *testing.T) { extraOptions := map[string]interface{}{ // Set a mongocryptd path that does not exist. If Connect() attempts to start // mongocryptd, it will cause an error. "mongocryptdPath": "/does/not/exist", } // If we're using the crypt_shared library, set the "cryptSharedLibRequired" option // to true and the "cryptSharedLibPath" option to the crypt_shared library path from // the CRYPT_SHARED_LIB_PATH environment variable. If we're not using the // crypt_shared library, explicitly disable loading the crypt_shared library. if tc.useCryptSharedLib { extraOptions["cryptSharedLibRequired"] = true extraOptions["cryptSharedLibPath"] = cryptSharedLibPath } else { extraOptions["__cryptSharedLibDisabledForTestOnly"] = true } _, err := NewClient(options.Client(). SetAutoEncryptionOptions(options.AutoEncryption(). SetKmsProviders(map[string]map[string]interface{}{ "local": {"key": make([]byte, 96)}, }). SetExtraOptions(extraOptions))) // If we're using the crypt_shared library, expect that Connect() doesn't attempt to spawn // mongocryptd and no error is returned. If we're not using the crypt_shared library, // expect that Connect() tries to spawn mongocryptd and returns an error. if tc.useCryptSharedLib { assert.Nil(t, err, "Connect() error: %v", err) } else { assert.NotNil(t, err, "expected Connect() error, but got nil") } }) } }) }	18.57 KB	2025-05-25 12:27
📄 collection.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "context" "errors" "fmt" "reflect" "strings" "time" "go.mongodb.org/mongo-driver/bson" "go.mongodb.org/mongo-driver/bson/bsoncodec" "go.mongodb.org/mongo-driver/bson/bsontype" "go.mongodb.org/mongo-driver/bson/primitive" "go.mongodb.org/mongo-driver/internal/csfle" "go.mongodb.org/mongo-driver/mongo/description" "go.mongodb.org/mongo-driver/mongo/options" "go.mongodb.org/mongo-driver/mongo/readconcern" "go.mongodb.org/mongo-driver/mongo/readpref" "go.mongodb.org/mongo-driver/mongo/writeconcern" "go.mongodb.org/mongo-driver/x/bsonx/bsoncore" "go.mongodb.org/mongo-driver/x/mongo/driver" "go.mongodb.org/mongo-driver/x/mongo/driver/operation" "go.mongodb.org/mongo-driver/x/mongo/driver/session" ) // Collection is a handle to a MongoDB collection. It is safe for concurrent use by multiple goroutines. type Collection struct { client Client db Database name string readConcern readconcern.ReadConcern writeConcern writeconcern.WriteConcern readPreference readpref.ReadPref readSelector description.ServerSelector writeSelector description.ServerSelector bsonOpts options.BSONOptions registry bsoncodec.Registry } // aggregateParams is used to store information to configure an Aggregate operation. type aggregateParams struct { ctx context.Context pipeline interface{} client Client bsonOpts options.BSONOptions registry bsoncodec.Registry readConcern readconcern.ReadConcern writeConcern writeconcern.WriteConcern retryRead bool db string col string readSelector description.ServerSelector writeSelector description.ServerSelector readPreference readpref.ReadPref opts []options.AggregateOptions } func closeImplicitSession(sess session.Client) { if sess != nil && sess.IsImplicit { sess.EndSession() } } func newCollection(db Database, name string, opts ...options.CollectionOptions) Collection { collOpt := options.MergeCollectionOptions(opts...) rc := db.readConcern if collOpt.ReadConcern != nil { rc = collOpt.ReadConcern } wc := db.writeConcern if collOpt.WriteConcern != nil { wc = collOpt.WriteConcern } rp := db.readPreference if collOpt.ReadPreference != nil { rp = collOpt.ReadPreference } bsonOpts := db.bsonOpts if collOpt.BSONOptions != nil { bsonOpts = collOpt.BSONOptions } reg := db.registry if collOpt.Registry != nil { reg = collOpt.Registry } readSelector := description.CompositeSelector([]description.ServerSelector{ description.ReadPrefSelector(rp), description.LatencySelector(db.client.localThreshold), }) writeSelector := description.CompositeSelector([]description.ServerSelector{ description.WriteSelector(), description.LatencySelector(db.client.localThreshold), }) coll := &Collection{ client: db.client, db: db, name: name, readPreference: rp, readConcern: rc, writeConcern: wc, readSelector: readSelector, writeSelector: writeSelector, bsonOpts: bsonOpts, registry: reg, } return coll } func (coll Collection) copy() Collection { return &Collection{ client: coll.client, db: coll.db, name: coll.name, readConcern: coll.readConcern, writeConcern: coll.writeConcern, readPreference: coll.readPreference, readSelector: coll.readSelector, writeSelector: coll.writeSelector, registry: coll.registry, } } // 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 (coll Collection) Clone(opts ...options.CollectionOptions) (Collection, error) { copyColl := coll.copy() optsColl := options.MergeCollectionOptions(opts...) if optsColl.ReadConcern != nil { copyColl.readConcern = optsColl.ReadConcern } if optsColl.WriteConcern != nil { copyColl.writeConcern = optsColl.WriteConcern } if optsColl.ReadPreference != nil { copyColl.readPreference = optsColl.ReadPreference } if optsColl.Registry != nil { copyColl.registry = optsColl.Registry } copyColl.readSelector = description.CompositeSelector([]description.ServerSelector{ description.ReadPrefSelector(copyColl.readPreference), description.LatencySelector(copyColl.client.localThreshold), }) return copyColl, nil } // Name returns the name of the collection. func (coll Collection) Name() string { return coll.name } // Database returns the Database that was used to create the Collection. func (coll Collection) Database() Database { return coll.db } // 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.) func (coll Collection) BulkWrite(ctx context.Context, models []WriteModel, opts ...options.BulkWriteOptions) (BulkWriteResult, error) { if len(models) == 0 { return nil, ErrEmptySlice } if ctx == nil { ctx = context.Background() } sess := sessionFromContext(ctx) if sess == nil && coll.client.sessionPool != nil { sess = session.NewImplicitClientSession(coll.client.sessionPool, coll.client.id) defer sess.EndSession() } err := coll.client.validSession(sess) if err != nil { return nil, err } wc := coll.writeConcern if sess.TransactionRunning() { wc = nil } if !writeconcern.AckWrite(wc) { sess = nil } selector := makePinnedSelector(sess, coll.writeSelector) for _, model := range models { if model == nil { return nil, ErrNilDocument } } bwo := options.MergeBulkWriteOptions(opts...) op := bulkWrite{ comment: bwo.Comment, ordered: bwo.Ordered, bypassDocumentValidation: bwo.BypassDocumentValidation, models: models, session: sess, collection: coll, selector: selector, writeConcern: wc, let: bwo.Let, } err = op.execute(ctx) return &op.result, replaceErrors(err) } func (coll Collection) insert(ctx context.Context, documents []interface{}, opts ...options.InsertManyOptions) ([]interface{}, error) { if ctx == nil { ctx = context.Background() } result := make([]interface{}, len(documents)) docs := make([]bsoncore.Document, len(documents)) for i, doc := range documents { bsoncoreDoc, err := marshal(doc, coll.bsonOpts, coll.registry) if err != nil { return nil, err } bsoncoreDoc, id, err := ensureID(bsoncoreDoc, primitive.NilObjectID, coll.bsonOpts, coll.registry) if err != nil { return nil, err } docs[i] = bsoncoreDoc result[i] = id } sess := sessionFromContext(ctx) if sess == nil && coll.client.sessionPool != nil { sess = session.NewImplicitClientSession(coll.client.sessionPool, coll.client.id) defer sess.EndSession() } err := coll.client.validSession(sess) if err != nil { return nil, err } wc := coll.writeConcern if sess.TransactionRunning() { wc = nil } if !writeconcern.AckWrite(wc) { sess = nil } selector := makePinnedSelector(sess, coll.writeSelector) op := operation.NewInsert(docs...). Session(sess).WriteConcern(wc).CommandMonitor(coll.client.monitor). ServerSelector(selector).ClusterClock(coll.client.clock). Database(coll.db.name).Collection(coll.name). Deployment(coll.client.deployment).Crypt(coll.client.cryptFLE).Ordered(true). ServerAPI(coll.client.serverAPI).Timeout(coll.client.timeout).Logger(coll.client.logger) imo := options.MergeInsertManyOptions(opts...) if imo.BypassDocumentValidation != nil && imo.BypassDocumentValidation { op = op.BypassDocumentValidation(imo.BypassDocumentValidation) } if imo.Comment != nil { comment, err := marshalValue(imo.Comment, coll.bsonOpts, coll.registry) if err != nil { return nil, err } op = op.Comment(comment) } if imo.Ordered != nil { op = op.Ordered(imo.Ordered) } retry := driver.RetryNone if coll.client.retryWrites { retry = driver.RetryOncePerCommand } op = op.Retry(retry) err = op.Execute(ctx) var wce driver.WriteCommandError if !errors.As(err, &wce) { return result, err } // remove the ids that had writeErrors from result for i, we := range wce.WriteErrors { // i indexes have been removed before the current error, so the index is we.Index-i idIndex := int(we.Index) - i // if the insert is ordered, nothing after the error was inserted if imo.Ordered == nil \|\| imo.Ordered { result = result[:idIndex] break } result = append(result[:idIndex], result[idIndex+1:]...) } return result, err } // 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/. func (coll Collection) InsertOne(ctx context.Context, document interface{}, opts ...options.InsertOneOptions) (InsertOneResult, error) { ioOpts := options.MergeInsertOneOptions(opts...) imOpts := options.InsertMany() if ioOpts.BypassDocumentValidation != nil && ioOpts.BypassDocumentValidation { imOpts.SetBypassDocumentValidation(ioOpts.BypassDocumentValidation) } if ioOpts.Comment != nil { imOpts.SetComment(ioOpts.Comment) } res, err := coll.insert(ctx, []interface{}{document}, imOpts) rr, err := processWriteError(err) if rr&rrOne == 0 { return nil, err } return &InsertOneResult{InsertedID: res[0]}, err } // 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/. func (coll Collection) InsertMany(ctx context.Context, documents []interface{}, opts ...options.InsertManyOptions) (InsertManyResult, error) { if len(documents) == 0 { return nil, ErrEmptySlice } result, err := coll.insert(ctx, documents, opts...) rr, err := processWriteError(err) if rr&rrMany == 0 { return nil, err } imResult := &InsertManyResult{InsertedIDs: result} var writeException WriteException if !errors.As(err, &writeException) { return imResult, err } // create and return a BulkWriteException bwErrors := make([]BulkWriteError, 0, len(writeException.WriteErrors)) for _, we := range writeException.WriteErrors { bwErrors = append(bwErrors, BulkWriteError{ WriteError: we, Request: nil, }) } return imResult, BulkWriteException{ WriteErrors: bwErrors, WriteConcernError: writeException.WriteConcernError, Labels: writeException.Labels, } } func (coll Collection) delete(ctx context.Context, filter interface{}, deleteOne bool, expectedRr returnResult, opts ...options.DeleteOptions) (DeleteResult, error) { if ctx == nil { ctx = context.Background() } f, err := marshal(filter, coll.bsonOpts, coll.registry) if err != nil { return nil, err } sess := sessionFromContext(ctx) if sess == nil && coll.client.sessionPool != nil { sess = session.NewImplicitClientSession(coll.client.sessionPool, coll.client.id) defer sess.EndSession() } err = coll.client.validSession(sess) if err != nil { return nil, err } wc := coll.writeConcern if sess.TransactionRunning() { wc = nil } if !writeconcern.AckWrite(wc) { sess = nil } selector := makePinnedSelector(sess, coll.writeSelector) var limit int32 if deleteOne { limit = 1 } do := options.MergeDeleteOptions(opts...) didx, doc := bsoncore.AppendDocumentStart(nil) doc = bsoncore.AppendDocumentElement(doc, "q", f) doc = bsoncore.AppendInt32Element(doc, "limit", limit) if do.Collation != nil { doc = bsoncore.AppendDocumentElement(doc, "collation", do.Collation.ToDocument()) } if do.Hint != nil { if isUnorderedMap(do.Hint) { return nil, ErrMapForOrderedArgument{"hint"} } hint, err := marshalValue(do.Hint, coll.bsonOpts, coll.registry) if err != nil { return nil, err } doc = bsoncore.AppendValueElement(doc, "hint", hint) } doc, _ = bsoncore.AppendDocumentEnd(doc, didx) op := operation.NewDelete(doc). Session(sess).WriteConcern(wc).CommandMonitor(coll.client.monitor). ServerSelector(selector).ClusterClock(coll.client.clock). Database(coll.db.name).Collection(coll.name). Deployment(coll.client.deployment).Crypt(coll.client.cryptFLE).Ordered(true). ServerAPI(coll.client.serverAPI).Timeout(coll.client.timeout).Logger(coll.client.logger) if do.Comment != nil { comment, err := marshalValue(do.Comment, coll.bsonOpts, coll.registry) if err != nil { return nil, err } op = op.Comment(comment) } if do.Hint != nil { op = op.Hint(true) } if do.Let != nil { let, err := marshal(do.Let, coll.bsonOpts, coll.registry) if err != nil { return nil, err } op = op.Let(let) } // deleteMany cannot be retried retryMode := driver.RetryNone if deleteOne && coll.client.retryWrites { retryMode = driver.RetryOncePerCommand } op = op.Retry(retryMode) rr, err := processWriteError(op.Execute(ctx)) if rr&expectedRr == 0 { return nil, err } return &DeleteResult{DeletedCount: op.Result().N}, err } // 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/. func (coll Collection) DeleteOne(ctx context.Context, filter interface{}, opts ...options.DeleteOptions) (DeleteResult, error) { return coll.delete(ctx, filter, true, rrOne, opts...) } // 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/. func (coll Collection) DeleteMany(ctx context.Context, filter interface{}, opts ...options.DeleteOptions) (DeleteResult, error) { return coll.delete(ctx, filter, false, rrMany, opts...) } func (coll Collection) updateOrReplace(ctx context.Context, filter bsoncore.Document, update interface{}, multi bool, expectedRr returnResult, checkDollarKey bool, opts ...options.UpdateOptions) (UpdateResult, error) { if ctx == nil { ctx = context.Background() } uo := options.MergeUpdateOptions(opts...) // collation, arrayFilters, upsert, and hint are included on the individual update documents rather than as part of the // command updateDoc, err := createUpdateDoc( filter, update, uo.Hint, uo.ArrayFilters, uo.Collation, uo.Upsert, multi, checkDollarKey, coll.bsonOpts, coll.registry) if err != nil { return nil, err } sess := sessionFromContext(ctx) if sess == nil && coll.client.sessionPool != nil { sess = session.NewImplicitClientSession(coll.client.sessionPool, coll.client.id) defer sess.EndSession() } err = coll.client.validSession(sess) if err != nil { return nil, err } wc := coll.writeConcern if sess.TransactionRunning() { wc = nil } if !writeconcern.AckWrite(wc) { sess = nil } selector := makePinnedSelector(sess, coll.writeSelector) op := operation.NewUpdate(updateDoc). Session(sess).WriteConcern(wc).CommandMonitor(coll.client.monitor). ServerSelector(selector).ClusterClock(coll.client.clock). Database(coll.db.name).Collection(coll.name). Deployment(coll.client.deployment).Crypt(coll.client.cryptFLE).Hint(uo.Hint != nil). ArrayFilters(uo.ArrayFilters != nil).Ordered(true).ServerAPI(coll.client.serverAPI). Timeout(coll.client.timeout).Logger(coll.client.logger) if uo.Let != nil { let, err := marshal(uo.Let, coll.bsonOpts, coll.registry) if err != nil { return nil, err } op = op.Let(let) } if uo.BypassDocumentValidation != nil && uo.BypassDocumentValidation { op = op.BypassDocumentValidation(uo.BypassDocumentValidation) } if uo.Comment != nil { comment, err := marshalValue(uo.Comment, coll.bsonOpts, coll.registry) if err != nil { return nil, err } op = op.Comment(comment) } retry := driver.RetryNone // retryable writes are only enabled updateOne/replaceOne operations if !multi && coll.client.retryWrites { retry = driver.RetryOncePerCommand } op = op.Retry(retry) err = op.Execute(ctx) rr, err := processWriteError(err) if rr&expectedRr == 0 { return nil, err } opRes := op.Result() res := &UpdateResult{ MatchedCount: opRes.N, ModifiedCount: opRes.NModified, UpsertedCount: int64(len(opRes.Upserted)), } if len(opRes.Upserted) > 0 { res.UpsertedID = opRes.Upserted[0].ID res.MatchedCount-- } return res, err } // 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 (coll Collection) UpdateByID(ctx context.Context, id interface{}, update interface{}, opts ...options.UpdateOptions) (UpdateResult, error) { if id == nil { return nil, ErrNilValue } return coll.UpdateOne(ctx, bson.D{{"_id", id}}, update, opts...) } // 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/. func (coll Collection) UpdateOne(ctx context.Context, filter interface{}, update interface{}, opts ...options.UpdateOptions) (UpdateResult, error) { if ctx == nil { ctx = context.Background() } f, err := marshal(filter, coll.bsonOpts, coll.registry) if err != nil { return nil, err } return coll.updateOrReplace(ctx, f, update, false, rrOne, true, opts...) } // 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/. func (coll Collection) UpdateMany(ctx context.Context, filter interface{}, update interface{}, opts ...options.UpdateOptions) (UpdateResult, error) { if ctx == nil { ctx = context.Background() } f, err := marshal(filter, coll.bsonOpts, coll.registry) if err != nil { return nil, err } return coll.updateOrReplace(ctx, f, update, true, rrMany, true, opts...) } // 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/. func (coll Collection) ReplaceOne(ctx context.Context, filter interface{}, replacement interface{}, opts ...options.ReplaceOptions) (UpdateResult, error) { if ctx == nil { ctx = context.Background() } f, err := marshal(filter, coll.bsonOpts, coll.registry) if err != nil { return nil, err } r, err := marshal(replacement, coll.bsonOpts, coll.registry) if err != nil { return nil, err } if err := ensureNoDollarKey(r); err != nil { return nil, err } updateOptions := make([]options.UpdateOptions, 0, len(opts)) for _, opt := range opts { if opt == nil { continue } uOpts := options.Update() uOpts.BypassDocumentValidation = opt.BypassDocumentValidation uOpts.Collation = opt.Collation uOpts.Upsert = opt.Upsert uOpts.Hint = opt.Hint uOpts.Let = opt.Let uOpts.Comment = opt.Comment updateOptions = append(updateOptions, uOpts) } return coll.updateOrReplace(ctx, f, r, false, rrOne, false, updateOptions...) } // 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/. func (coll Collection) Aggregate(ctx context.Context, pipeline interface{}, opts ...options.AggregateOptions) (Cursor, error) { a := aggregateParams{ ctx: ctx, pipeline: pipeline, client: coll.client, registry: coll.registry, readConcern: coll.readConcern, writeConcern: coll.writeConcern, bsonOpts: coll.bsonOpts, retryRead: coll.client.retryReads, db: coll.db.name, col: coll.name, readSelector: coll.readSelector, writeSelector: coll.writeSelector, readPreference: coll.readPreference, opts: opts, } return aggregate(a) } // aggregate is the helper method for Aggregate func aggregate(a aggregateParams) (cur Cursor, err error) { if a.ctx == nil { a.ctx = context.Background() } pipelineArr, hasOutputStage, err := marshalAggregatePipeline(a.pipeline, a.bsonOpts, a.registry) if err != nil { return nil, err } sess := sessionFromContext(a.ctx) // Always close any created implicit sessions if aggregate returns an error. defer func() { if err != nil && sess != nil { closeImplicitSession(sess) } }() if sess == nil && a.client.sessionPool != nil { sess = session.NewImplicitClientSession(a.client.sessionPool, a.client.id) } if err = a.client.validSession(sess); err != nil { return nil, err } var wc writeconcern.WriteConcern if hasOutputStage { wc = a.writeConcern } rc := a.readConcern if sess.TransactionRunning() { wc = nil rc = nil } if !writeconcern.AckWrite(wc) { closeImplicitSession(sess) sess = nil } selector := makeReadPrefSelector(sess, a.readSelector, a.client.localThreshold) if hasOutputStage { selector = makeOutputAggregateSelector(sess, a.readPreference, a.client.localThreshold) } ao := options.MergeAggregateOptions(a.opts...) cursorOpts := a.client.createBaseCursorOptions() cursorOpts.MarshalValueEncoderFn = newEncoderFn(a.bsonOpts, a.registry) op := operation.NewAggregate(pipelineArr). Session(sess). WriteConcern(wc). ReadConcern(rc). ReadPreference(a.readPreference). CommandMonitor(a.client.monitor). ServerSelector(selector). ClusterClock(a.client.clock). Database(a.db). Collection(a.col). Deployment(a.client.deployment). Crypt(a.client.cryptFLE). ServerAPI(a.client.serverAPI). HasOutputStage(hasOutputStage). Timeout(a.client.timeout). MaxTime(ao.MaxTime) if ao.AllowDiskUse != nil { op.AllowDiskUse(ao.AllowDiskUse) } // ignore batchSize of 0 with $out if ao.BatchSize != nil && !(ao.BatchSize == 0 && hasOutputStage) { op.BatchSize(ao.BatchSize) cursorOpts.BatchSize = ao.BatchSize } if ao.BypassDocumentValidation != nil && ao.BypassDocumentValidation { op.BypassDocumentValidation(ao.BypassDocumentValidation) } if ao.Collation != nil { op.Collation(bsoncore.Document(ao.Collation.ToDocument())) } if ao.MaxAwaitTime != nil { cursorOpts.MaxTimeMS = int64(ao.MaxAwaitTime / time.Millisecond) } if ao.Comment != nil { op.Comment(ao.Comment) commentVal, err := marshalValue(ao.Comment, a.bsonOpts, a.registry) if err != nil { return nil, err } cursorOpts.Comment = commentVal } if ao.Hint != nil { if isUnorderedMap(ao.Hint) { return nil, ErrMapForOrderedArgument{"hint"} } hintVal, err := marshalValue(ao.Hint, a.bsonOpts, a.registry) if err != nil { return nil, err } op.Hint(hintVal) } if ao.Let != nil { let, err := marshal(ao.Let, a.bsonOpts, a.registry) if err != nil { return nil, err } op.Let(let) } if ao.Custom != nil { // Marshal all custom options before passing to the aggregate operation. Return // any errors from Marshaling. customOptions := make(map[string]bsoncore.Value) for optionName, optionValue := range ao.Custom { bsonType, bsonData, err := bson.MarshalValueWithRegistry(a.registry, optionValue) if err != nil { return nil, err } optionValueBSON := bsoncore.Value{Type: bsonType, Data: bsonData} customOptions[optionName] = optionValueBSON } op.CustomOptions(customOptions) } retry := driver.RetryNone if a.retryRead && !hasOutputStage { retry = driver.RetryOncePerCommand } op = op.Retry(retry) err = op.Execute(a.ctx) if err != nil { if wce, ok := err.(driver.WriteCommandError); ok && wce.WriteConcernError != nil { return nil, convertDriverWriteConcernError(wce.WriteConcernError) } return nil, replaceErrors(err) } bc, err := op.Result(cursorOpts) if err != nil { return nil, replaceErrors(err) } cursor, err := newCursorWithSession(bc, a.client.bsonOpts, a.registry, sess) return cursor, replaceErrors(err) } // 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). func (coll Collection) CountDocuments(ctx context.Context, filter interface{}, opts ...options.CountOptions) (int64, error) { if ctx == nil { ctx = context.Background() } countOpts := options.MergeCountOptions(opts...) pipelineArr, err := countDocumentsAggregatePipeline(filter, coll.bsonOpts, coll.registry, countOpts) if err != nil { return 0, err } sess := sessionFromContext(ctx) if sess == nil && coll.client.sessionPool != nil { sess = session.NewImplicitClientSession(coll.client.sessionPool, coll.client.id) defer sess.EndSession() } if err = coll.client.validSession(sess); err != nil { return 0, err } rc := coll.readConcern if sess.TransactionRunning() { rc = nil } selector := makeReadPrefSelector(sess, coll.readSelector, coll.client.localThreshold) op := operation.NewAggregate(pipelineArr).Session(sess).ReadConcern(rc).ReadPreference(coll.readPreference). CommandMonitor(coll.client.monitor).ServerSelector(selector).ClusterClock(coll.client.clock).Database(coll.db.name). Collection(coll.name).Deployment(coll.client.deployment).Crypt(coll.client.cryptFLE).ServerAPI(coll.client.serverAPI). Timeout(coll.client.timeout).MaxTime(countOpts.MaxTime) if countOpts.Collation != nil { op.Collation(bsoncore.Document(countOpts.Collation.ToDocument())) } if countOpts.Comment != nil { op.Comment(countOpts.Comment) } if countOpts.Hint != nil { if isUnorderedMap(countOpts.Hint) { return 0, ErrMapForOrderedArgument{"hint"} } hintVal, err := marshalValue(countOpts.Hint, coll.bsonOpts, coll.registry) if err != nil { return 0, err } op.Hint(hintVal) } retry := driver.RetryNone if coll.client.retryReads { retry = driver.RetryOncePerCommand } op = op.Retry(retry) err = op.Execute(ctx) if err != nil { return 0, replaceErrors(err) } batch := op.ResultCursorResponse().FirstBatch if batch == nil { return 0, errors.New("invalid response from server, no 'firstBatch' field") } docs, err := batch.Documents() if err != nil \|\| len(docs) == 0 { return 0, nil } val, ok := docs[0].Lookup("n").AsInt64OK() if !ok { return 0, errors.New("invalid response from server, no 'n' field") } return val, nil } // 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/. func (coll Collection) EstimatedDocumentCount(ctx context.Context, opts ...options.EstimatedDocumentCountOptions) (int64, error) { if ctx == nil { ctx = context.Background() } sess := sessionFromContext(ctx) var err error if sess == nil && coll.client.sessionPool != nil { sess = session.NewImplicitClientSession(coll.client.sessionPool, coll.client.id) defer sess.EndSession() } err = coll.client.validSession(sess) if err != nil { return 0, err } rc := coll.readConcern if sess.TransactionRunning() { rc = nil } co := options.MergeEstimatedDocumentCountOptions(opts...) selector := makeReadPrefSelector(sess, coll.readSelector, coll.client.localThreshold) op := operation.NewCount().Session(sess).ClusterClock(coll.client.clock). Database(coll.db.name).Collection(coll.name).CommandMonitor(coll.client.monitor). Deployment(coll.client.deployment).ReadConcern(rc).ReadPreference(coll.readPreference). ServerSelector(selector).Crypt(coll.client.cryptFLE).ServerAPI(coll.client.serverAPI). Timeout(coll.client.timeout).MaxTime(co.MaxTime) if co.Comment != nil { comment, err := marshalValue(co.Comment, coll.bsonOpts, coll.registry) if err != nil { return 0, err } op = op.Comment(comment) } retry := driver.RetryNone if coll.client.retryReads { retry = driver.RetryOncePerCommand } op.Retry(retry) err = op.Execute(ctx) return op.Result().N, replaceErrors(err) } // 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/. func (coll Collection) Distinct(ctx context.Context, fieldName string, filter interface{}, opts ...options.DistinctOptions) ([]interface{}, error) { if ctx == nil { ctx = context.Background() } f, err := marshal(filter, coll.bsonOpts, coll.registry) if err != nil { return nil, err } sess := sessionFromContext(ctx) if sess == nil && coll.client.sessionPool != nil { sess = session.NewImplicitClientSession(coll.client.sessionPool, coll.client.id) defer sess.EndSession() } err = coll.client.validSession(sess) if err != nil { return nil, err } rc := coll.readConcern if sess.TransactionRunning() { rc = nil } selector := makeReadPrefSelector(sess, coll.readSelector, coll.client.localThreshold) option := options.MergeDistinctOptions(opts...) op := operation.NewDistinct(fieldName, f). Session(sess).ClusterClock(coll.client.clock). Database(coll.db.name).Collection(coll.name).CommandMonitor(coll.client.monitor). Deployment(coll.client.deployment).ReadConcern(rc).ReadPreference(coll.readPreference). ServerSelector(selector).Crypt(coll.client.cryptFLE).ServerAPI(coll.client.serverAPI). Timeout(coll.client.timeout).MaxTime(option.MaxTime) if option.Collation != nil { op.Collation(bsoncore.Document(option.Collation.ToDocument())) } if option.Comment != nil { comment, err := marshalValue(option.Comment, coll.bsonOpts, coll.registry) if err != nil { return nil, err } op.Comment(comment) } retry := driver.RetryNone if coll.client.retryReads { retry = driver.RetryOncePerCommand } op = op.Retry(retry) err = op.Execute(ctx) if err != nil { return nil, replaceErrors(err) } arr, ok := op.Result().Values.ArrayOK() if !ok { return nil, fmt.Errorf("response field 'values' is type array, but received BSON type %s", op.Result().Values.Type) } values, err := arr.Values() if err != nil { return nil, err } retArray := make([]interface{}, len(values)) for i, val := range values { raw := bson.RawValue{Type: val.Type, Value: val.Data} err = raw.Unmarshal(&retArray[i]) if err != nil { return nil, err } } return retArray, replaceErrors(err) } // 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/. func (coll Collection) Find(ctx context.Context, filter interface{}, opts ...options.FindOptions) (cur Cursor, err error) { if ctx == nil { ctx = context.Background() } f, err := marshal(filter, coll.bsonOpts, coll.registry) if err != nil { return nil, err } sess := sessionFromContext(ctx) // Always close any created implicit sessions if Find returns an error. defer func() { if err != nil && sess != nil { closeImplicitSession(sess) } }() if sess == nil && coll.client.sessionPool != nil { sess = session.NewImplicitClientSession(coll.client.sessionPool, coll.client.id) } err = coll.client.validSession(sess) if err != nil { return nil, err } rc := coll.readConcern if sess.TransactionRunning() { rc = nil } fo := options.MergeFindOptions(opts...) selector := makeReadPrefSelector(sess, coll.readSelector, coll.client.localThreshold) op := operation.NewFind(f). Session(sess).ReadConcern(rc).ReadPreference(coll.readPreference). CommandMonitor(coll.client.monitor).ServerSelector(selector). ClusterClock(coll.client.clock).Database(coll.db.name).Collection(coll.name). Deployment(coll.client.deployment).Crypt(coll.client.cryptFLE).ServerAPI(coll.client.serverAPI). Timeout(coll.client.timeout).MaxTime(fo.MaxTime).Logger(coll.client.logger) cursorOpts := coll.client.createBaseCursorOptions() cursorOpts.MarshalValueEncoderFn = newEncoderFn(coll.bsonOpts, coll.registry) if fo.AllowDiskUse != nil { op.AllowDiskUse(fo.AllowDiskUse) } if fo.AllowPartialResults != nil { op.AllowPartialResults(fo.AllowPartialResults) } if fo.BatchSize != nil { cursorOpts.BatchSize = fo.BatchSize op.BatchSize(fo.BatchSize) } if fo.Collation != nil { op.Collation(bsoncore.Document(fo.Collation.ToDocument())) } if fo.Comment != nil { op.Comment(fo.Comment) commentVal, err := marshalValue(fo.Comment, coll.bsonOpts, coll.registry) if err != nil { return nil, err } cursorOpts.Comment = commentVal } if fo.CursorType != nil { switch fo.CursorType { case options.Tailable: op.Tailable(true) case options.TailableAwait: op.Tailable(true) op.AwaitData(true) } } if fo.Hint != nil { if isUnorderedMap(fo.Hint) { return nil, ErrMapForOrderedArgument{"hint"} } hint, err := marshalValue(fo.Hint, coll.bsonOpts, coll.registry) if err != nil { return nil, err } op.Hint(hint) } if fo.Let != nil { let, err := marshal(fo.Let, coll.bsonOpts, coll.registry) if err != nil { return nil, err } op.Let(let) } if fo.Limit != nil { limit := fo.Limit if limit < 0 { limit = -1 limit op.SingleBatch(true) } cursorOpts.Limit = int32(limit) op.Limit(limit) } if fo.Max != nil { max, err := marshal(fo.Max, coll.bsonOpts, coll.registry) if err != nil { return nil, err } op.Max(max) } if fo.MaxAwaitTime != nil { cursorOpts.MaxTimeMS = int64(fo.MaxAwaitTime / time.Millisecond) } if fo.Min != nil { min, err := marshal(fo.Min, coll.bsonOpts, coll.registry) if err != nil { return nil, err } op.Min(min) } if fo.NoCursorTimeout != nil { op.NoCursorTimeout(fo.NoCursorTimeout) } if fo.OplogReplay != nil { op.OplogReplay(fo.OplogReplay) } if fo.Projection != nil { proj, err := marshal(fo.Projection, coll.bsonOpts, coll.registry) if err != nil { return nil, err } op.Projection(proj) } if fo.ReturnKey != nil { op.ReturnKey(fo.ReturnKey) } if fo.ShowRecordID != nil { op.ShowRecordID(fo.ShowRecordID) } if fo.Skip != nil { op.Skip(fo.Skip) } if fo.Snapshot != nil { op.Snapshot(fo.Snapshot) } if fo.Sort != nil { if isUnorderedMap(fo.Sort) { return nil, ErrMapForOrderedArgument{"sort"} } sort, err := marshal(fo.Sort, coll.bsonOpts, coll.registry) if err != nil { return nil, err } op.Sort(sort) } retry := driver.RetryNone if coll.client.retryReads { retry = driver.RetryOncePerCommand } op = op.Retry(retry) if err = op.Execute(ctx); err != nil { return nil, replaceErrors(err) } bc, err := op.Result(cursorOpts) if err != nil { return nil, replaceErrors(err) } return newCursorWithSession(bc, coll.bsonOpts, coll.registry, sess) } // 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/. func (coll Collection) FindOne(ctx context.Context, filter interface{}, opts ...options.FindOneOptions) SingleResult { if ctx == nil { ctx = context.Background() } findOpts := make([]options.FindOptions, 0, len(opts)) for _, opt := range opts { if opt == nil { continue } findOpts = append(findOpts, &options.FindOptions{ AllowPartialResults: opt.AllowPartialResults, BatchSize: opt.BatchSize, Collation: opt.Collation, Comment: opt.Comment, CursorType: opt.CursorType, Hint: opt.Hint, Max: opt.Max, MaxAwaitTime: opt.MaxAwaitTime, MaxTime: opt.MaxTime, Min: opt.Min, NoCursorTimeout: opt.NoCursorTimeout, OplogReplay: opt.OplogReplay, Projection: opt.Projection, ReturnKey: opt.ReturnKey, ShowRecordID: opt.ShowRecordID, Skip: opt.Skip, Snapshot: opt.Snapshot, Sort: opt.Sort, }) } // Unconditionally send a limit to make sure only one document is returned and the cursor is not kept open // by the server. findOpts = append(findOpts, options.Find().SetLimit(-1)) cursor, err := coll.Find(ctx, filter, findOpts...) return &SingleResult{ ctx: ctx, cur: cursor, bsonOpts: coll.bsonOpts, reg: coll.registry, err: replaceErrors(err), } } func (coll Collection) findAndModify(ctx context.Context, op operation.FindAndModify) SingleResult { if ctx == nil { ctx = context.Background() } sess := sessionFromContext(ctx) var err error if sess == nil && coll.client.sessionPool != nil { sess = session.NewImplicitClientSession(coll.client.sessionPool, coll.client.id) defer sess.EndSession() } err = coll.client.validSession(sess) if err != nil { return &SingleResult{err: err} } wc := coll.writeConcern if sess.TransactionRunning() { wc = nil } if !writeconcern.AckWrite(wc) { sess = nil } selector := makePinnedSelector(sess, coll.writeSelector) retry := driver.RetryNone if coll.client.retryWrites { retry = driver.RetryOnce } op = op.Session(sess). WriteConcern(wc). CommandMonitor(coll.client.monitor). ServerSelector(selector). ClusterClock(coll.client.clock). Database(coll.db.name). Collection(coll.name). Deployment(coll.client.deployment). Retry(retry). Crypt(coll.client.cryptFLE) _, err = processWriteError(op.Execute(ctx)) if err != nil { return &SingleResult{err: err} } return &SingleResult{ ctx: ctx, rdr: bson.Raw(op.Result().Value), bsonOpts: coll.bsonOpts, reg: coll.registry, } } // 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/. func (coll Collection) FindOneAndDelete(ctx context.Context, filter interface{}, opts ...options.FindOneAndDeleteOptions) SingleResult { f, err := marshal(filter, coll.bsonOpts, coll.registry) if err != nil { return &SingleResult{err: err} } fod := options.MergeFindOneAndDeleteOptions(opts...) op := operation.NewFindAndModify(f).Remove(true).ServerAPI(coll.client.serverAPI).Timeout(coll.client.timeout). MaxTime(fod.MaxTime) if fod.Collation != nil { op = op.Collation(bsoncore.Document(fod.Collation.ToDocument())) } if fod.Comment != nil { comment, err := marshalValue(fod.Comment, coll.bsonOpts, coll.registry) if err != nil { return &SingleResult{err: err} } op = op.Comment(comment) } if fod.Projection != nil { proj, err := marshal(fod.Projection, coll.bsonOpts, coll.registry) if err != nil { return &SingleResult{err: err} } op = op.Fields(proj) } if fod.Sort != nil { if isUnorderedMap(fod.Sort) { return &SingleResult{err: ErrMapForOrderedArgument{"sort"}} } sort, err := marshal(fod.Sort, coll.bsonOpts, coll.registry) if err != nil { return &SingleResult{err: err} } op = op.Sort(sort) } if fod.Hint != nil { if isUnorderedMap(fod.Hint) { return &SingleResult{err: ErrMapForOrderedArgument{"hint"}} } hint, err := marshalValue(fod.Hint, coll.bsonOpts, coll.registry) if err != nil { return &SingleResult{err: err} } op = op.Hint(hint) } if fod.Let != nil { let, err := marshal(fod.Let, coll.bsonOpts, coll.registry) if err != nil { return &SingleResult{err: err} } op = op.Let(let) } return coll.findAndModify(ctx, op) } // 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/. func (coll Collection) FindOneAndReplace(ctx context.Context, filter interface{}, replacement interface{}, opts ...options.FindOneAndReplaceOptions) SingleResult { f, err := marshal(filter, coll.bsonOpts, coll.registry) if err != nil { return &SingleResult{err: err} } r, err := marshal(replacement, coll.bsonOpts, coll.registry) if err != nil { return &SingleResult{err: err} } if firstElem, err := r.IndexErr(0); err == nil && strings.HasPrefix(firstElem.Key(), "$") { return &SingleResult{err: errors.New("replacement document cannot contain keys beginning with '$'")} } fo := options.MergeFindOneAndReplaceOptions(opts...) op := operation.NewFindAndModify(f).Update(bsoncore.Value{Type: bsontype.EmbeddedDocument, Data: r}). ServerAPI(coll.client.serverAPI).Timeout(coll.client.timeout).MaxTime(fo.MaxTime) if fo.BypassDocumentValidation != nil && fo.BypassDocumentValidation { op = op.BypassDocumentValidation(fo.BypassDocumentValidation) } if fo.Collation != nil { op = op.Collation(bsoncore.Document(fo.Collation.ToDocument())) } if fo.Comment != nil { comment, err := marshalValue(fo.Comment, coll.bsonOpts, coll.registry) if err != nil { return &SingleResult{err: err} } op = op.Comment(comment) } if fo.Projection != nil { proj, err := marshal(fo.Projection, coll.bsonOpts, coll.registry) if err != nil { return &SingleResult{err: err} } op = op.Fields(proj) } if fo.ReturnDocument != nil { op = op.NewDocument(fo.ReturnDocument == options.After) } if fo.Sort != nil { if isUnorderedMap(fo.Sort) { return &SingleResult{err: ErrMapForOrderedArgument{"sort"}} } sort, err := marshal(fo.Sort, coll.bsonOpts, coll.registry) if err != nil { return &SingleResult{err: err} } op = op.Sort(sort) } if fo.Upsert != nil { op = op.Upsert(fo.Upsert) } if fo.Hint != nil { if isUnorderedMap(fo.Hint) { return &SingleResult{err: ErrMapForOrderedArgument{"hint"}} } hint, err := marshalValue(fo.Hint, coll.bsonOpts, coll.registry) if err != nil { return &SingleResult{err: err} } op = op.Hint(hint) } if fo.Let != nil { let, err := marshal(fo.Let, coll.bsonOpts, coll.registry) if err != nil { return &SingleResult{err: err} } op = op.Let(let) } return coll.findAndModify(ctx, op) } // 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/. func (coll Collection) FindOneAndUpdate(ctx context.Context, filter interface{}, update interface{}, opts ...options.FindOneAndUpdateOptions) SingleResult { if ctx == nil { ctx = context.Background() } f, err := marshal(filter, coll.bsonOpts, coll.registry) if err != nil { return &SingleResult{err: err} } fo := options.MergeFindOneAndUpdateOptions(opts...) op := operation.NewFindAndModify(f).ServerAPI(coll.client.serverAPI).Timeout(coll.client.timeout). MaxTime(fo.MaxTime) u, err := marshalUpdateValue(update, coll.bsonOpts, coll.registry, true) if err != nil { return &SingleResult{err: err} } op = op.Update(u) if fo.ArrayFilters != nil { af := fo.ArrayFilters reg := coll.registry if af.Registry != nil { reg = af.Registry } filtersDoc, err := marshalValue(af.Filters, coll.bsonOpts, reg) if err != nil { return &SingleResult{err: err} } op = op.ArrayFilters(filtersDoc.Data) } if fo.BypassDocumentValidation != nil && fo.BypassDocumentValidation { op = op.BypassDocumentValidation(fo.BypassDocumentValidation) } if fo.Collation != nil { op = op.Collation(bsoncore.Document(fo.Collation.ToDocument())) } if fo.Comment != nil { comment, err := marshalValue(fo.Comment, coll.bsonOpts, coll.registry) if err != nil { return &SingleResult{err: err} } op = op.Comment(comment) } if fo.Projection != nil { proj, err := marshal(fo.Projection, coll.bsonOpts, coll.registry) if err != nil { return &SingleResult{err: err} } op = op.Fields(proj) } if fo.ReturnDocument != nil { op = op.NewDocument(fo.ReturnDocument == options.After) } if fo.Sort != nil { if isUnorderedMap(fo.Sort) { return &SingleResult{err: ErrMapForOrderedArgument{"sort"}} } sort, err := marshal(fo.Sort, coll.bsonOpts, coll.registry) if err != nil { return &SingleResult{err: err} } op = op.Sort(sort) } if fo.Upsert != nil { op = op.Upsert(fo.Upsert) } if fo.Hint != nil { if isUnorderedMap(fo.Hint) { return &SingleResult{err: ErrMapForOrderedArgument{"hint"}} } hint, err := marshalValue(fo.Hint, coll.bsonOpts, coll.registry) if err != nil { return &SingleResult{err: err} } op = op.Hint(hint) } if fo.Let != nil { let, err := marshal(fo.Let, coll.bsonOpts, coll.registry) if err != nil { return &SingleResult{err: err} } op = op.Let(let) } return coll.findAndModify(ctx, op) } // 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). func (coll Collection) Watch(ctx context.Context, pipeline interface{}, opts ...options.ChangeStreamOptions) (ChangeStream, error) { csConfig := changeStreamConfig{ readConcern: coll.readConcern, readPreference: coll.readPreference, client: coll.client, bsonOpts: coll.bsonOpts, registry: coll.registry, streamType: CollectionStream, collectionName: coll.Name(), databaseName: coll.db.Name(), crypt: coll.client.cryptFLE, } return newChangeStream(ctx, csConfig, pipeline, opts...) } // Indexes returns an IndexView instance that can be used to perform operations on the indexes for the collection. func (coll Collection) Indexes() IndexView { return IndexView{coll: coll} } // SearchIndexes returns a SearchIndexView instance that can be used to perform operations on the search indexes for the collection. func (coll Collection) SearchIndexes() SearchIndexView { return SearchIndexView{ coll: coll, } } // 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 (coll Collection) Drop(ctx context.Context) error { // Follow Client-Side Encryption specification to check for encryptedFields. // Drop does not have an encryptedFields option. See: GODRIVER-2413. // Check for encryptedFields from the client EncryptedFieldsMap. // Check for encryptedFields from the server if EncryptedFieldsMap is set. ef := coll.db.getEncryptedFieldsFromMap(coll.name) if ef == nil && coll.db.client.encryptedFieldsMap != nil { var err error if ef, err = coll.db.getEncryptedFieldsFromServer(ctx, coll.name); err != nil { return err } } if ef != nil { return coll.dropEncryptedCollection(ctx, ef) } return coll.drop(ctx) } // dropEncryptedCollection drops a collection with EncryptedFields. func (coll Collection) dropEncryptedCollection(ctx context.Context, ef interface{}) error { efBSON, err := marshal(ef, coll.bsonOpts, coll.registry) if err != nil { return fmt.Errorf("error transforming document: %w", err) } // Drop the two encryption-related, associated collections: `escCollection` and `ecocCollection`. // Drop ESCCollection. escCollection, err := csfle.GetEncryptedStateCollectionName(efBSON, coll.name, csfle.EncryptedStateCollection) if err != nil { return err } if err := coll.db.Collection(escCollection).drop(ctx); err != nil { return err } // Drop ECOCCollection. ecocCollection, err := csfle.GetEncryptedStateCollectionName(efBSON, coll.name, csfle.EncryptedCompactionCollection) if err != nil { return err } if err := coll.db.Collection(ecocCollection).drop(ctx); err != nil { return err } // Drop the data collection. return coll.drop(ctx) } // drop drops a collection without EncryptedFields. func (coll Collection) drop(ctx context.Context) error { if ctx == nil { ctx = context.Background() } sess := sessionFromContext(ctx) if sess == nil && coll.client.sessionPool != nil { sess = session.NewImplicitClientSession(coll.client.sessionPool, coll.client.id) defer sess.EndSession() } err := coll.client.validSession(sess) if err != nil { return err } wc := coll.writeConcern if sess.TransactionRunning() { wc = nil } if !writeconcern.AckWrite(wc) { sess = nil } selector := makePinnedSelector(sess, coll.writeSelector) op := operation.NewDropCollection(). Session(sess).WriteConcern(wc).CommandMonitor(coll.client.monitor). ServerSelector(selector).ClusterClock(coll.client.clock). Database(coll.db.name).Collection(coll.name). Deployment(coll.client.deployment).Crypt(coll.client.cryptFLE). ServerAPI(coll.client.serverAPI).Timeout(coll.client.timeout) err = op.Execute(ctx) // ignore namespace not found errors driverErr, ok := err.(driver.Error) if !ok \|\| (ok && !driverErr.NamespaceNotFound()) { return replaceErrors(err) } return nil } type pinnedServerSelector struct { stringer fmt.Stringer fallback description.ServerSelector session session.Client } func (pss pinnedServerSelector) String() string { if pss.stringer == nil { return "" } return pss.stringer.String() } func (pss pinnedServerSelector) SelectServer( t description.Topology, svrs []description.Server, ) ([]description.Server, error) { if pss.session != nil && pss.session.PinnedServer != nil { // If there is a pinned server, try to find it in the list of candidates. for _, candidate := range svrs { if candidate.Addr == pss.session.PinnedServer.Addr { return []description.Server{candidate}, nil } } return nil, nil } return pss.fallback.SelectServer(t, svrs) } func makePinnedSelector(sess session.Client, fallback description.ServerSelector) description.ServerSelector { pss := pinnedServerSelector{ session: sess, fallback: fallback, } if srvSelectorStringer, ok := fallback.(fmt.Stringer); ok { pss.stringer = srvSelectorStringer } return pss } func makeReadPrefSelector(sess session.Client, selector description.ServerSelector, localThreshold time.Duration) description.ServerSelector { if sess != nil && sess.TransactionRunning() { selector = description.CompositeSelector([]description.ServerSelector{ description.ReadPrefSelector(sess.CurrentRp), description.LatencySelector(localThreshold), }) } return makePinnedSelector(sess, selector) } func makeOutputAggregateSelector(sess session.Client, rp readpref.ReadPref, localThreshold time.Duration) description.ServerSelector { if sess != nil && sess.TransactionRunning() { // Use current transaction's read preference if available rp = sess.CurrentRp } selector := description.CompositeSelector([]description.ServerSelector{ description.OutputAggregateSelector(rp), description.LatencySelector(localThreshold), }) return makePinnedSelector(sess, selector) } // isUnorderedMap returns true if val is a map with more than 1 element. It is typically used to // check for unordered Go values that are used in nested command documents where different field // orders mean different things. Examples are the "sort" and "hint" fields. func isUnorderedMap(val interface{}) bool { refValue := reflect.ValueOf(val) return refValue.Kind() == reflect.Map && refValue.Len() > 1 }	60.87 KB	2025-05-25 12:27
📄 collection_test.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "errors" "testing" "go.mongodb.org/mongo-driver/bson" "go.mongodb.org/mongo-driver/internal/assert" "go.mongodb.org/mongo-driver/mongo/options" "go.mongodb.org/mongo-driver/mongo/readconcern" "go.mongodb.org/mongo-driver/mongo/readpref" "go.mongodb.org/mongo-driver/mongo/writeconcern" ) const ( testDbName = "unitTestDb" ) func setupColl(name string, opts ...options.CollectionOptions) Collection { db := setupDb(testDbName) return db.Collection(name, opts...) } func compareColls(t testing.T, expected Collection, got Collection) { assert.Equal(t, expected.readPreference, got.readPreference, "mismatch; expected read preference %v, got %v", expected.readPreference, got.readPreference) assert.Equal(t, expected.readConcern, got.readConcern, "mismatch; expected read concern %v, got %v", expected.readConcern, got.readConcern) assert.Equal(t, expected.writeConcern, got.writeConcern, "mismatch; expected write concern %v, got %v", expected.writeConcern, got.writeConcern) } func TestCollection(t testing.T) { t.Run("initialize", func(t testing.T) { name := "foo" coll := setupColl(name) assert.Equal(t, name, coll.Name(), "expected coll name %v, got %v", name, coll.Name()) assert.NotNil(t, coll.Database(), "expected valid database, got nil") }) t.Run("specified options", func(t testing.T) { rpPrimary := readpref.Primary() rpSecondary := readpref.Secondary() wc1 := writeconcern.New(writeconcern.W(5)) wc2 := writeconcern.New(writeconcern.W(10)) rcLocal := readconcern.Local() rcMajority := readconcern.Majority() opts := options.Collection().SetReadPreference(rpPrimary).SetReadConcern(rcLocal).SetWriteConcern(wc1). SetReadPreference(rpSecondary).SetReadConcern(rcMajority).SetWriteConcern(wc2) expected := &Collection{ readConcern: rcMajority, readPreference: rpSecondary, writeConcern: wc2, } got := setupColl("foo", opts) compareColls(t, expected, got) }) t.Run("inherit options", func(t testing.T) { rpPrimary := readpref.Primary() rcLocal := readconcern.Local() wc1 := writeconcern.New(writeconcern.W(10)) db := setupDb("foo", options.Database().SetReadPreference(rpPrimary).SetReadConcern(rcLocal)) coll := db.Collection("bar", options.Collection().SetWriteConcern(wc1)) expected := &Collection{ readPreference: rpPrimary, readConcern: rcLocal, writeConcern: wc1, } compareColls(t, expected, coll) }) t.Run("replace topology error", func(t testing.T) { coll := setupColl("foo") doc := bson.D{} update := bson.D{{"$update", bson.D{{"x", 1}}}} _, err := coll.InsertOne(bgCtx, doc) assert.Equal(t, ErrClientDisconnected, err, "expected error %v, got %v", ErrClientDisconnected, err) _, err = coll.InsertMany(bgCtx, []interface{}{doc}) assert.Equal(t, ErrClientDisconnected, err, "expected error %v, got %v", ErrClientDisconnected, err) _, err = coll.DeleteOne(bgCtx, doc) assert.Equal(t, ErrClientDisconnected, err, "expected error %v, got %v", ErrClientDisconnected, err) _, err = coll.DeleteMany(bgCtx, doc) assert.Equal(t, ErrClientDisconnected, err, "expected error %v, got %v", ErrClientDisconnected, err) _, err = coll.UpdateOne(bgCtx, doc, update) assert.Equal(t, ErrClientDisconnected, err, "expected error %v, got %v", ErrClientDisconnected, err) _, err = coll.UpdateMany(bgCtx, doc, update) assert.Equal(t, ErrClientDisconnected, err, "expected error %v, got %v", ErrClientDisconnected, err) _, err = coll.ReplaceOne(bgCtx, doc, doc) assert.Equal(t, ErrClientDisconnected, err, "expected error %v, got %v", ErrClientDisconnected, err) _, err = coll.Aggregate(bgCtx, Pipeline{}) assert.Equal(t, ErrClientDisconnected, err, "expected error %v, got %v", ErrClientDisconnected, err) _, err = coll.EstimatedDocumentCount(bgCtx) assert.Equal(t, ErrClientDisconnected, err, "expected error %v, got %v", ErrClientDisconnected, err) _, err = coll.CountDocuments(bgCtx, doc) assert.Equal(t, ErrClientDisconnected, err, "expected error %v, got %v", ErrClientDisconnected, err) _, err = coll.Distinct(bgCtx, "x", doc) assert.Equal(t, ErrClientDisconnected, err, "expected error %v, got %v", ErrClientDisconnected, err) _, err = coll.Find(bgCtx, doc) assert.Equal(t, ErrClientDisconnected, err, "expected error %v, got %v", ErrClientDisconnected, err) err = coll.FindOne(bgCtx, doc).Err() assert.Equal(t, ErrClientDisconnected, err, "expected error %v, got %v", ErrClientDisconnected, err) err = coll.FindOneAndDelete(bgCtx, doc).Err() assert.Equal(t, ErrClientDisconnected, err, "expected error %v, got %v", ErrClientDisconnected, err) err = coll.FindOneAndReplace(bgCtx, doc, doc).Err() assert.Equal(t, ErrClientDisconnected, err, "expected error %v, got %v", ErrClientDisconnected, err) err = coll.FindOneAndUpdate(bgCtx, doc, update).Err() assert.Equal(t, ErrClientDisconnected, err, "expected error %v, got %v", ErrClientDisconnected, err) }) t.Run("database accessor", func(t testing.T) { coll := setupColl("bar") dbName := coll.Database().Name() assert.Equal(t, testDbName, dbName, "expected db name %v, got %v", testDbName, dbName) }) t.Run("nil document error", func(t testing.T) { coll := setupColl("foo") doc := bson.D{} _, err := coll.InsertOne(bgCtx, nil) assert.Equal(t, ErrNilDocument, err, "expected error %v, got %v", ErrNilDocument, err) _, err = coll.InsertMany(bgCtx, nil) assert.Equal(t, ErrEmptySlice, err, "expected error %v, got %v", ErrEmptySlice, err) _, err = coll.InsertMany(bgCtx, []interface{}{}) assert.Equal(t, ErrEmptySlice, err, "expected error %v, got %v", ErrEmptySlice, err) _, err = coll.DeleteOne(bgCtx, nil) assert.Equal(t, ErrNilDocument, err, "expected error %v, got %v", ErrNilDocument, err) _, err = coll.DeleteMany(bgCtx, nil) assert.Equal(t, ErrNilDocument, err, "expected error %v, got %v", ErrNilDocument, err) _, err = coll.UpdateOne(bgCtx, nil, doc) assert.Equal(t, ErrNilDocument, err, "expected error %v, got %v", ErrNilDocument, err) _, err = coll.UpdateOne(bgCtx, doc, nil) assert.Equal(t, ErrNilDocument, err, "expected error %v, got %v", ErrNilDocument, err) _, err = coll.UpdateMany(bgCtx, nil, doc) assert.Equal(t, ErrNilDocument, err, "expected error %v, got %v", ErrNilDocument, err) _, err = coll.UpdateMany(bgCtx, doc, nil) assert.Equal(t, ErrNilDocument, err, "expected error %v, got %v", ErrNilDocument, err) _, err = coll.ReplaceOne(bgCtx, nil, doc) assert.Equal(t, ErrNilDocument, err, "expected error %v, got %v", ErrNilDocument, err) _, err = coll.ReplaceOne(bgCtx, doc, nil) assert.Equal(t, ErrNilDocument, err, "expected error %v, got %v", ErrNilDocument, err) _, err = coll.CountDocuments(bgCtx, nil) assert.Equal(t, ErrNilDocument, err, "expected error %v, got %v", ErrNilDocument, err) _, err = coll.Distinct(bgCtx, "x", nil) assert.Equal(t, ErrNilDocument, err, "expected error %v, got %v", ErrNilDocument, err) _, err = coll.Find(bgCtx, nil) assert.Equal(t, ErrNilDocument, err, "expected error %v, got %v", ErrNilDocument, err) err = coll.FindOne(bgCtx, nil).Err() assert.Equal(t, ErrNilDocument, err, "expected error %v, got %v", ErrNilDocument, err) err = coll.FindOneAndDelete(bgCtx, nil).Err() assert.Equal(t, ErrNilDocument, err, "expected error %v, got %v", ErrNilDocument, err) err = coll.FindOneAndReplace(bgCtx, nil, doc).Err() assert.Equal(t, ErrNilDocument, err, "expected error %v, got %v", ErrNilDocument, err) err = coll.FindOneAndReplace(bgCtx, doc, nil).Err() assert.Equal(t, ErrNilDocument, err, "expected error %v, got %v", ErrNilDocument, err) err = coll.FindOneAndUpdate(bgCtx, nil, doc).Err() assert.Equal(t, ErrNilDocument, err, "expected error %v, got %v", ErrNilDocument, err) err = coll.FindOneAndUpdate(bgCtx, doc, nil).Err() assert.Equal(t, ErrNilDocument, err, "expected error %v, got %v", ErrNilDocument, err) _, err = coll.BulkWrite(bgCtx, nil) assert.Equal(t, ErrEmptySlice, err, "expected error %v, got %v", ErrEmptySlice, err) _, err = coll.BulkWrite(bgCtx, []WriteModel{}) assert.Equal(t, ErrEmptySlice, err, "expected error %v, got %v", ErrEmptySlice, err) _, err = coll.BulkWrite(bgCtx, []WriteModel{nil}) assert.Equal(t, ErrNilDocument, err, "expected error %v, got %v", ErrNilDocument, err) aggErr := errors.New("can only marshal slices and arrays into aggregation pipelines, but got invalid") _, err = coll.Aggregate(bgCtx, nil) assert.Equal(t, aggErr, err, "expected error %v, got %v", aggErr, err) _, err = coll.Watch(bgCtx, nil) assert.Equal(t, aggErr, err, "expected error %v, got %v", aggErr, err) }) }	8.76 KB	2025-05-25 12:27
📄 crud_examples_test.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo_test import ( "context" "errors" "fmt" "log" "sync" "time" "go.mongodb.org/mongo-driver/bson" "go.mongodb.org/mongo-driver/bson/primitive" "go.mongodb.org/mongo-driver/mongo" "go.mongodb.org/mongo-driver/mongo/options" "go.mongodb.org/mongo-driver/mongo/readconcern" "go.mongodb.org/mongo-driver/mongo/readpref" ) // Client examples func ExampleClient_ListDatabaseNames() { 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.Fatal(err) } for _, db := range result { fmt.Println(db) } } func ExampleClient_Watch() { 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.Fatal(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) } } // Database examples func ExampleDatabase_CreateCollection() { 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.Fatal(err) } } func ExampleDatabase_CreateView() { 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.Fatal(err) } } func ExampleDatabase_ListCollectionNames() { 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.Fatal(err) } for _, coll := range result { fmt.Println(coll) } } func ExampleDatabase_RunCommand() { 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.Fatal(err) } fmt.Println(result) } func ExampleDatabase_Watch() { 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.Fatal(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) } } // Collection examples func ExampleCollection_Aggregate() { 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().SetMaxTime(2 time.Second) cursor, err := coll.Aggregate( context.TODO(), mongo.Pipeline{groupStage}, opts) if err != nil { log.Fatal(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.Fatal(err) } for _, result := range results { fmt.Printf( "name %v appears %v times\n", result["_id"], result["numTimes"]) } } func ExampleCollection_BulkWrite() { var coll mongo.Collection var firstID, secondID primitive.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.Fatal(err) } fmt.Printf( "inserted %v and deleted %v documents\n", res.InsertedCount, res.DeletedCount) } func ExampleCollection_CountDocuments() { var coll mongo.Collection // Count the number of times the name "Bob" appears in the collection. // Specify the MaxTime option to limit the amount of time the operation can // run on the server. opts := options.Count().SetMaxTime(2 * time.Second) count, err := coll.CountDocuments( context.TODO(), bson.D{{"name", "Bob"}}, opts) if err != nil { log.Fatal(err) } fmt.Printf("name Bob appears in %v documents", count) } func ExampleCollection_DeleteMany() { 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.Fatal(err) } fmt.Printf("deleted %v documents\n", res.DeletedCount) } func ExampleCollection_DeleteOne() { 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.Fatal(err) } fmt.Printf("deleted %v documents\n", res.DeletedCount) } func ExampleCollection_Distinct() { var coll mongo.Collection // Find all unique values for the "name" field for documents in which the // "age" field is greater than 25. // Specify the MaxTime option to limit the amount of time the operation can // run on the server. filter := bson.D{{"age", bson.D{{"$gt", 25}}}} opts := options.Distinct().SetMaxTime(2 time.Second) values, err := coll.Distinct(context.TODO(), "name", filter, opts) if err != nil { log.Fatal(err) } for _, value := range values { fmt.Println(value) } } func ExampleCollection_EstimatedDocumentCount() { var coll mongo.Collection // Get and print an estimated of the number of documents in the collection. // Specify the MaxTime option to limit the amount of time the operation can // run on the server. opts := options.EstimatedDocumentCount().SetMaxTime(2 time.Second) count, err := coll.EstimatedDocumentCount(context.TODO(), opts) if err != nil { log.Fatal(err) } fmt.Printf("estimated document count: %v", count) } func ExampleCollection_Find() { 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.Fatal(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.Fatal(err) } for _, result := range results { fmt.Println(result) } } func ExampleCollection_FindOne() { var coll mongo.Collection var id primitive.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.Fatal(err) } fmt.Printf("found document %v", result) } func ExampleCollection_FindOneAndDelete() { var coll mongo.Collection var id primitive.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.Fatal(err) } fmt.Printf("deleted document %v", deletedDocument) } func ExampleCollection_FindOneAndReplace() { var coll mongo.Collection var id primitive.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.Fatal(err) } fmt.Printf("replaced document %v", replacedDocument) } func ExampleCollection_FindOneAndUpdate() { var coll mongo.Collection var id primitive.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.Fatal(err) } fmt.Printf("updated document %v", updatedDocument) } func ExampleCollection_InsertMany() { 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.Fatal(err) } fmt.Printf("inserted documents with IDs %v\n", res.InsertedIDs) } func ExampleCollection_InsertOne() { var coll mongo.Collection // Insert the document {name: "Alice"}. res, err := coll.InsertOne(context.TODO(), bson.D{{"name", "Alice"}}) if err != nil { log.Fatal(err) } fmt.Printf("inserted document with ID %v\n", res.InsertedID) } func ExampleCollection_ReplaceOne() { var coll mongo.Collection var id primitive.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.Fatal(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) } } func ExampleCollection_UpdateMany() { 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.Fatal(err) } if result.MatchedCount != 0 { fmt.Println("matched and replaced an existing document") return } } func ExampleCollection_UpdateOne() { var coll mongo.Collection var id primitive.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.Fatal(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) } } func ExampleCollection_Watch() { 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.Fatal(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) } } // Session examples func ExampleWithSession() { // 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. opts := options.Session().SetDefaultReadConcern(readconcern.Majority()) sess, err := client.StartSession(opts) if err != nil { log.Fatal(err) } defer sess.EndSession(context.TODO()) // Call WithSession to start a transaction within the new session. err = mongo.WithSession( context.TODO(), sess, func(ctx mongo.SessionContext) error { // Use the mongo.SessionContext 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.Fatal(err) } } func ExampleClient_UseSessionWithOptions() { 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. opts := options.Session().SetDefaultReadConcern(readconcern.Majority()) err := client.UseSessionWithOptions( context.TODO(), opts, func(ctx mongo.SessionContext) error { // Use the mongo.SessionContext as the Context parameter for // InsertOne and FindOne so both operations are run under the new // Session. if err := ctx.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. _ = ctx.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. _ = ctx.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 ctx.CommitTransaction(context.Background()) }) if err != nil { log.Fatal(err) } } func ExampleClient_StartSession_withTransaction() { // 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. opts := options.Session().SetDefaultReadConcern(readconcern.Majority()) sess, err := client.StartSession(opts) if err != nil { log.Fatal(err) } defer sess.EndSession(context.TODO()) // Specify the ReadPreference option to set the read preference to primary // preferred for this transaction. txnOpts := options.Transaction(). SetReadPreference(readpref.PrimaryPreferred()) result, err := sess.WithTransaction( context.TODO(), func(ctx mongo.SessionContext) (interface{}, error) { // Use the mongo.SessionContext 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.Fatal(err) } fmt.Printf("result: %v\n", result) } func ExampleNewSessionContext() { 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 mongo.SessionContext 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) } } // Cursor examples func ExampleCursor_All() { var cursor mongo.Cursor var results []bson.M if err := cursor.All(context.TODO(), &results); err != nil { log.Fatal(err) } fmt.Println(results) } func ExampleCursor_Next() { 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.Fatal(err) } fmt.Println(result) } if err := cursor.Err(); err != nil { log.Fatal(err) } } func ExampleCursor_TryNext() { 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.Fatal(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.Fatal(err) } if cursor.ID() == 0 { break } } } func ExampleCursor_RemainingBatchLength() { // 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) } } } // ChangeStream examples func ExampleChangeStream_Next() { 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.Fatal(err) } fmt.Println(event) } if err := stream.Err(); err != nil { log.Fatal(err) } } func ExampleChangeStream_TryNext() { 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.Fatal(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.Fatal(err) } if stream.ID() == 0 { break } } } func ExampleChangeStream_ResumeToken() { 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.Fatal(err) } defer newStream.Close(context.TODO()) } // IndexView examples func ExampleIndexView_CreateMany() { 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 opts := options.CreateIndexes().SetMaxTime(2 * time.Second) names, err := indexView.CreateMany(context.TODO(), models, opts) if err != nil { log.Fatal(err) } fmt.Printf("created indexes %v\n", names) } func ExampleIndexView_List() { var indexView mongo.IndexView // Specify the MaxTime option to limit the amount of time the operation can // run on the server opts := options.ListIndexes().SetMaxTime(2 time.Second) cursor, err := indexView.List(context.TODO(), opts) if err != nil { log.Fatal(err) } // Get a slice of all indexes returned and print them out. var results []bson.M if err = cursor.All(context.TODO(), &results); err != nil { log.Fatal(err) } fmt.Println(results) } func ExampleCollection_Find_primitiveRegex() { ctx := context.TODO() clientOptions := options.Client().ApplyURI("mongodb://localhost:27017") // Connect to a mongodb server. client, err := mongo.Connect(ctx, 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", primitive.Regex{Pattern: "^m", Options: "i"}}} _, err = coll.Find(ctx, filter) if err != nil { panic(err) } } func ExampleCollection_Find_regex() { ctx := context.TODO() clientOptions := options.Client().ApplyURI("mongodb://localhost:27017") // Connect to a mongodb server. client, err := mongo.Connect(ctx, 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) } }	32.06 KB	2025-05-25 12:27
📄 crypt_retrievers.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "context" "go.mongodb.org/mongo-driver/x/bsonx/bsoncore" ) // keyRetriever gets keys from the key vault collection. type keyRetriever struct { coll Collection } func (kr keyRetriever) cryptKeys(ctx context.Context, filter bsoncore.Document) ([]bsoncore.Document, error) { // Remove the explicit session from the context if one is set. // The explicit session may be from a different client. ctx = NewSessionContext(ctx, nil) cursor, err := kr.coll.Find(ctx, filter) if err != nil { return nil, EncryptionKeyVaultError{Wrapped: err} } defer cursor.Close(ctx) var results []bsoncore.Document for cursor.Next(ctx) { cur := make([]byte, len(cursor.Current)) copy(cur, cursor.Current) results = append(results, cur) } if err = cursor.Err(); err != nil { return nil, EncryptionKeyVaultError{Wrapped: err} } return results, nil } // collInfoRetriever gets info for collections from a database. type collInfoRetriever struct { client Client } func (cir collInfoRetriever) cryptCollInfo(ctx context.Context, db string, filter bsoncore.Document) (bsoncore.Document, error) { // Remove the explicit session from the context if one is set. // The explicit session may be from a different client. ctx = NewSessionContext(ctx, nil) cursor, err := cir.client.Database(db).ListCollections(ctx, filter) if err != nil { return nil, err } defer cursor.Close(ctx) if !cursor.Next(ctx) { return nil, cursor.Err() } res := make([]byte, len(cursor.Current)) copy(res, cursor.Current) return res, nil }	1.79 KB	2025-05-25 12:27
📄 cursor.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "context" "errors" "fmt" "io" "reflect" "time" "go.mongodb.org/mongo-driver/bson" "go.mongodb.org/mongo-driver/bson/bsoncodec" "go.mongodb.org/mongo-driver/bson/bsonrw" "go.mongodb.org/mongo-driver/mongo/options" "go.mongodb.org/mongo-driver/x/bsonx/bsoncore" "go.mongodb.org/mongo-driver/x/mongo/driver" "go.mongodb.org/mongo-driver/x/mongo/driver/session" ) // 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. 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 bc batchCursor batch bsoncore.DocumentSequence batchLength int bsonOpts options.BSONOptions registry bsoncodec.Registry clientSession session.Client err error } func newCursor( bc batchCursor, bsonOpts options.BSONOptions, registry bsoncodec.Registry, ) (Cursor, error) { return newCursorWithSession(bc, bsonOpts, registry, nil) } func newCursorWithSession( bc batchCursor, bsonOpts options.BSONOptions, registry bsoncodec.Registry, clientSession session.Client, ) (Cursor, error) { if registry == nil { registry = bson.DefaultRegistry } if bc == nil { return nil, errors.New("batch cursor must not be nil") } c := &Cursor{ bc: bc, bsonOpts: bsonOpts, registry: registry, clientSession: clientSession, } if bc.ID() == 0 { c.closeImplicitSession() } // Initialize just the batchLength here so RemainingBatchLength will return an accurate result. The actual batch // will be pulled up by the first Next/TryNext call. c.batchLength = c.bc.Batch().DocumentCount() return c, nil } func newEmptyCursor() Cursor { return &Cursor{bc: driver.NewEmptyBatchCursor()} } // NewCursorFromDocuments creates a new Cursor pre-loaded with the provided documents, error and registry. If no registry is provided, // bson.DefaultRegistry 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 NewCursorFromDocuments(documents []interface{}, err error, registry bsoncodec.Registry) (Cursor, error) { if registry == nil { registry = bson.DefaultRegistry } // Convert documents slice to a sequence-style byte array. var docsBytes []byte for _, doc := range documents { switch t := doc.(type) { case nil: return nil, ErrNilDocument case []byte: // Slight optimization so we'll just use MarshalBSON and not go through the codec machinery. doc = bson.Raw(t) } var marshalErr error docsBytes, marshalErr = bson.MarshalAppendWithRegistry(registry, docsBytes, doc) if marshalErr != nil { return nil, marshalErr } } c := &Cursor{ bc: driver.NewBatchCursorFromDocuments(docsBytes), registry: registry, err: err, } // Initialize batch and batchLength here. The underlying batch cursor will be preloaded with the // provided contents, and thus already has a batch before calls to Next/TryNext. c.batch = c.bc.Batch() c.batchLength = c.bc.Batch().DocumentCount() return c, nil } // ID returns the ID of this cursor, or 0 if the cursor has been closed or exhausted. func (c Cursor) ID() int64 { return c.bc.ID() } // 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. func (c Cursor) Next(ctx context.Context) bool { return c.next(ctx, false) } // 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. func (c Cursor) TryNext(ctx context.Context) bool { return c.next(ctx, true) } func (c Cursor) next(ctx context.Context, nonBlocking bool) bool { // return false right away if the cursor has already errored. if c.err != nil { return false } if ctx == nil { ctx = context.Background() } doc, err := c.batch.Next() switch { case err == nil: // Consume the next document in the current batch. c.batchLength-- c.Current = bson.Raw(doc) return true case errors.Is(err, io.EOF): // Need to do a getMore default: c.err = err return false } // call the Next method in a loop until at least one document is returned in the next batch or // the context times out. for { // If we don't have a next batch if !c.bc.Next(ctx) { // Do we have an error? If so we return false. c.err = replaceErrors(c.bc.Err()) if c.err != nil { return false } // Is the cursor ID zero? if c.bc.ID() == 0 { c.closeImplicitSession() return false } // empty batch, but cursor is still valid. // use nonBlocking to determine if we should continue or return control to the caller. if nonBlocking { return false } continue } // close the implicit session if this was the last getMore if c.bc.ID() == 0 { c.closeImplicitSession() } // Use the new batch to update the batch and batchLength fields. Consume the first document in the batch. c.batch = c.bc.Batch() c.batchLength = c.batch.DocumentCount() doc, err = c.batch.Next() switch { case err == nil: c.batchLength-- c.Current = bson.Raw(doc) return true case errors.Is(err, io.EOF): // Empty batch so we continue default: c.err = err return false } } } func getDecoder( data []byte, opts options.BSONOptions, reg bsoncodec.Registry, ) (bson.Decoder, error) { dec, err := bson.NewDecoder(bsonrw.NewBSONDocumentReader(data)) if err != nil { return nil, err } if opts != nil { if opts.AllowTruncatingDoubles { dec.AllowTruncatingDoubles() } if opts.BinaryAsSlice { dec.BinaryAsSlice() } if opts.DefaultDocumentD { dec.DefaultDocumentD() } if opts.DefaultDocumentM { dec.DefaultDocumentM() } if opts.UseJSONStructTags { dec.UseJSONStructTags() } if opts.UseLocalTimeZone { dec.UseLocalTimeZone() } if opts.ZeroMaps { dec.ZeroMaps() } if opts.ZeroStructs { dec.ZeroStructs() } } if reg != nil { // TODO:(GODRIVER-2719): Remove error handling. if err := dec.SetRegistry(reg); err != nil { return nil, err } } return dec, nil } // 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 (c Cursor) Decode(val interface{}) error { dec, err := getDecoder(c.Current, c.bsonOpts, c.registry) if err != nil { return fmt.Errorf("error configuring BSON decoder: %w", err) } return dec.Decode(val) } // Err returns the last error seen by the Cursor, or nil if no error has occurred. func (c Cursor) Err() error { return c.err } // 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 (c Cursor) Close(ctx context.Context) error { defer c.closeImplicitSession() return replaceErrors(c.bc.Close(ctx)) } // 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. func (c Cursor) All(ctx context.Context, results interface{}) error { resultsVal := reflect.ValueOf(results) if resultsVal.Kind() != reflect.Ptr { return fmt.Errorf("results argument must be a pointer to a slice, but was a %s", resultsVal.Kind()) } sliceVal := resultsVal.Elem() if sliceVal.Kind() == reflect.Interface { sliceVal = sliceVal.Elem() } if sliceVal.Kind() != reflect.Slice { return fmt.Errorf("results argument must be a pointer to a slice, but was a pointer to %s", sliceVal.Kind()) } elementType := sliceVal.Type().Elem() var index int var err error // Defer a call to Close to try to clean up the cursor server-side when all // documents have not been exhausted. Use context.Background() to ensure Close // completes even if the context passed to All has errored. defer c.Close(context.Background()) batch := c.batch // exhaust the current batch before iterating the batch cursor for { sliceVal, index, err = c.addFromBatch(sliceVal, elementType, batch, index) if err != nil { return err } if !c.bc.Next(ctx) { break } batch = c.bc.Batch() } if err = replaceErrors(c.bc.Err()); err != nil { return err } resultsVal.Elem().Set(sliceVal.Slice(0, index)) return nil } // 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 (c Cursor) RemainingBatchLength() int { return c.batchLength } // addFromBatch adds all documents from batch to sliceVal starting at the given index. It returns the new slice value, // the next empty index in the slice, and an error if one occurs. func (c Cursor) addFromBatch(sliceVal reflect.Value, elemType reflect.Type, batch bsoncore.DocumentSequence, index int) (reflect.Value, int, error) { docs, err := batch.Documents() if err != nil { return sliceVal, index, err } for _, doc := range docs { if sliceVal.Len() == index { // slice is full newElem := reflect.New(elemType) sliceVal = reflect.Append(sliceVal, newElem.Elem()) sliceVal = sliceVal.Slice(0, sliceVal.Cap()) } currElem := sliceVal.Index(index).Addr().Interface() dec, err := getDecoder(doc, c.bsonOpts, c.registry) if err != nil { return sliceVal, index, fmt.Errorf("error configuring BSON decoder: %w", err) } err = dec.Decode(currElem) if err != nil { return sliceVal, index, err } index++ } return sliceVal, index, nil } func (c Cursor) closeImplicitSession() { if c.clientSession != nil && c.clientSession.IsImplicit { c.clientSession.EndSession() } } // 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 (c Cursor) SetBatchSize(batchSize int32) { c.bc.SetBatchSize(batchSize) } // SetMaxTime 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 (c Cursor) SetMaxTime(dur time.Duration) { c.bc.SetMaxTime(dur) } // SetComment will set a user-configurable comment that can be used to identify // the operation in server logs. func (c Cursor) SetComment(comment interface{}) { c.bc.SetComment(comment) } // 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 BatchCursorFromCursor(c Cursor) driver.BatchCursor { bc, _ := c.bc.(*driver.BatchCursor) return bc }	12.76 KB	2025-05-25 12:27
📄 cursor_test.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "context" "fmt" "testing" "time" "go.mongodb.org/mongo-driver/bson" "go.mongodb.org/mongo-driver/internal/assert" "go.mongodb.org/mongo-driver/internal/require" "go.mongodb.org/mongo-driver/mongo/options" "go.mongodb.org/mongo-driver/x/bsonx/bsoncore" "go.mongodb.org/mongo-driver/x/mongo/driver" ) type testBatchCursor struct { batches []bsoncore.DocumentSequence batch bsoncore.DocumentSequence closed bool } func newTestBatchCursor(numBatches, batchSize int) testBatchCursor { batches := make([]bsoncore.DocumentSequence, 0, numBatches) counter := 0 for batch := 0; batch < numBatches; batch++ { var docSequence []byte for doc := 0; doc < batchSize; doc++ { var elem []byte elem = bsoncore.AppendInt32Element(elem, "foo", int32(counter)) counter++ var doc []byte doc = bsoncore.BuildDocumentFromElements(doc, elem) docSequence = append(docSequence, doc...) } batches = append(batches, &bsoncore.DocumentSequence{ Style: bsoncore.SequenceStyle, Data: docSequence, }) } return &testBatchCursor{ batches: batches, } } func (tbc testBatchCursor) ID() int64 { if len(tbc.batches) == 0 { return 0 // cursor exhausted } return 10 } func (tbc testBatchCursor) Next(context.Context) bool { if len(tbc.batches) == 0 { return false } tbc.batch = tbc.batches[0] tbc.batches = tbc.batches[1:] return true } func (tbc testBatchCursor) Batch() bsoncore.DocumentSequence { return tbc.batch } func (tbc testBatchCursor) Server() driver.Server { return nil } func (tbc testBatchCursor) Err() error { return nil } func (tbc testBatchCursor) Close(context.Context) error { tbc.closed = true return nil } func (tbc testBatchCursor) SetBatchSize(int32) {} func (tbc testBatchCursor) SetComment(interface{}) {} func (tbc testBatchCursor) SetMaxTime(time.Duration) {} func TestCursor(t testing.T) { t.Run("loops until docs available", func(t testing.T) {}) t.Run("returns false on context cancellation", func(t testing.T) {}) t.Run("returns false if error occurred", func(t testing.T) {}) t.Run("returns false if ID is zero and no more docs", func(t testing.T) {}) t.Run("TestAll", func(t testing.T) { t.Run("errors if argument is not pointer to slice", func(t testing.T) { cursor, err := newCursor(newTestBatchCursor(1, 5), nil, nil) assert.Nil(t, err, "newCursor error: %v", err) err = cursor.All(context.Background(), []bson.D{}) assert.NotNil(t, err, "expected error, got nil") }) t.Run("fills slice with all documents", func(t testing.T) { cursor, err := newCursor(newTestBatchCursor(1, 5), nil, nil) assert.Nil(t, err, "newCursor error: %v", err) var docs []bson.D err = cursor.All(context.Background(), &docs) assert.Nil(t, err, "All error: %v", err) assert.Equal(t, 5, len(docs), "expected 5 docs, got %v", len(docs)) for index, doc := range docs { expected := bson.D{{"foo", int32(index)}} assert.Equal(t, expected, doc, "expected doc %v, got %v", expected, doc) } }) t.Run("decodes each document into slice type", func(t testing.T) { cursor, err := newCursor(newTestBatchCursor(1, 5), nil, nil) assert.Nil(t, err, "newCursor error: %v", err) type Document struct { Foo int32 `bson:"foo"` } var docs []Document err = cursor.All(context.Background(), &docs) assert.Nil(t, err, "All error: %v", err) assert.Equal(t, 5, len(docs), "expected 5 documents, got %v", len(docs)) for index, doc := range docs { expected := Document{Foo: int32(index)} assert.Equal(t, expected, doc, "expected doc %v, got %v", expected, doc) } }) t.Run("multiple batches are included", func(t testing.T) { cursor, err := newCursor(newTestBatchCursor(2, 5), nil, nil) assert.Nil(t, err, "newCursor error: %v", err) var docs []bson.D err = cursor.All(context.Background(), &docs) assert.Nil(t, err, "All error: %v", err) assert.Equal(t, 10, len(docs), "expected 10 docs, got %v", len(docs)) for index, doc := range docs { expected := bson.D{{"foo", int32(index)}} assert.Equal(t, expected, doc, "expected doc %v, got %v", expected, doc) } }) t.Run("cursor is closed after All is called", func(t testing.T) { var docs []bson.D tbc := newTestBatchCursor(1, 5) cursor, err := newCursor(tbc, nil, nil) assert.Nil(t, err, "newCursor error: %v", err) err = cursor.All(context.Background(), &docs) assert.Nil(t, err, "All error: %v", err) assert.True(t, tbc.closed, "expected batch cursor to be closed but was not") }) t.Run("does not error given interface as parameter", func(t testing.T) { var docs interface{} = []bson.D{} cursor, err := newCursor(newTestBatchCursor(1, 5), nil, nil) assert.Nil(t, err, "newCursor error: %v", err) err = cursor.All(context.Background(), &docs) assert.Nil(t, err, "expected Nil, got error: %v", err) assert.Equal(t, 5, len(docs.([]bson.D)), "expected 5 documents, got %v", len(docs.([]bson.D))) }) t.Run("errors when not given pointer to slice", func(t testing.T) { var docs interface{} = "test" cursor, err := newCursor(newTestBatchCursor(1, 5), nil, nil) assert.Nil(t, err, "newCursor error: %v", err) err = cursor.All(context.Background(), &docs) assert.NotNil(t, err, "expected error, got: %v", err) }) t.Run("with BSONOptions", func(t testing.T) { cursor, err := newCursor( newTestBatchCursor(1, 5), &options.BSONOptions{ UseJSONStructTags: true, }, nil) require.NoError(t, err, "newCursor error") type myDocument struct { A int32 `json:"foo"` } var got []myDocument err = cursor.All(context.Background(), &got) require.NoError(t, err, "All error") want := []myDocument{{A: 0}, {A: 1}, {A: 2}, {A: 3}, {A: 4}} assert.Equal(t, want, got, "expected and actual All results are different") }) }) } func TestNewCursorFromDocuments(t testing.T) { // Mock documents returned by Find in a Cursor. t.Run("mock Find", func(t testing.T) { findResult := []interface{}{ bson.D{{"_id", 0}, {"foo", "bar"}}, bson.D{{"_id", 1}, {"baz", "qux"}}, bson.D{{"_id", 2}, {"quux", "quuz"}}, } cur, err := NewCursorFromDocuments(findResult, nil, nil) assert.Nil(t, err, "NewCursorFromDocuments error: %v", err) // Assert that decoded documents are as expected. var i int for cur.Next(context.Background()) { docBytes, err := bson.Marshal(findResult[i]) assert.Nil(t, err, "Marshal error: %v", err) expectedDecoded := bson.Raw(docBytes) var decoded bson.Raw err = cur.Decode(&decoded) assert.Nil(t, err, "Decode error: %v", err) assert.Equal(t, expectedDecoded, decoded, "expected decoded document %v of Cursor to be %v, got %v", i, expectedDecoded, decoded) i++ } assert.Equal(t, 3, i, "expected 3 calls to cur.Next, got %v", i) // Check for error on Cursor. assert.Nil(t, cur.Err(), "Cursor error: %v", cur.Err()) // Assert that a call to cur.Close will not fail. err = cur.Close(context.Background()) assert.Nil(t, err, "Close error: %v", err) }) // Mock an error in a Cursor. t.Run("mock Find with error", func(t *testing.T) { mockErr := fmt.Errorf("mock error") findResult := []interface{}{bson.D{{"_id", 0}, {"foo", "bar"}}} cur, err := NewCursorFromDocuments(findResult, mockErr, nil) assert.Nil(t, err, "NewCursorFromDocuments error: %v", err) // Assert that a call to Next will return false because of existing error. next := cur.Next(context.Background()) assert.False(t, next, "expected call to Next to return false, got true") // Check for error on Cursor. assert.NotNil(t, cur.Err(), "expected Cursor error, got nil") assert.Equal(t, mockErr, cur.Err(), "expected Cursor error %v, got %v", mockErr, cur.Err()) }) }	7.92 KB	2025-05-25 12:27
📄 database.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "context" "errors" "fmt" "time" "go.mongodb.org/mongo-driver/bson" "go.mongodb.org/mongo-driver/bson/bsoncodec" "go.mongodb.org/mongo-driver/internal/csfle" "go.mongodb.org/mongo-driver/mongo/description" "go.mongodb.org/mongo-driver/mongo/options" "go.mongodb.org/mongo-driver/mongo/readconcern" "go.mongodb.org/mongo-driver/mongo/readpref" "go.mongodb.org/mongo-driver/mongo/writeconcern" "go.mongodb.org/mongo-driver/x/bsonx/bsoncore" "go.mongodb.org/mongo-driver/x/mongo/driver" "go.mongodb.org/mongo-driver/x/mongo/driver/operation" "go.mongodb.org/mongo-driver/x/mongo/driver/session" ) var ( defaultRunCmdOpts = []options.RunCmdOptions{options.RunCmd().SetReadPreference(readpref.Primary())} ) // Database is a handle to a MongoDB database. It is safe for concurrent use by multiple goroutines. type Database struct { client Client name string readConcern readconcern.ReadConcern writeConcern writeconcern.WriteConcern readPreference readpref.ReadPref readSelector description.ServerSelector writeSelector description.ServerSelector bsonOpts options.BSONOptions registry bsoncodec.Registry } func newDatabase(client Client, name string, opts ...options.DatabaseOptions) Database { dbOpt := options.MergeDatabaseOptions(opts...) rc := client.readConcern if dbOpt.ReadConcern != nil { rc = dbOpt.ReadConcern } rp := client.readPreference if dbOpt.ReadPreference != nil { rp = dbOpt.ReadPreference } wc := client.writeConcern if dbOpt.WriteConcern != nil { wc = dbOpt.WriteConcern } bsonOpts := client.bsonOpts if dbOpt.BSONOptions != nil { bsonOpts = dbOpt.BSONOptions } reg := client.registry if dbOpt.Registry != nil { reg = dbOpt.Registry } db := &Database{ client: client, name: name, readPreference: rp, readConcern: rc, writeConcern: wc, bsonOpts: bsonOpts, registry: reg, } db.readSelector = description.CompositeSelector([]description.ServerSelector{ description.ReadPrefSelector(db.readPreference), description.LatencySelector(db.client.localThreshold), }) db.writeSelector = description.CompositeSelector([]description.ServerSelector{ description.WriteSelector(), description.LatencySelector(db.client.localThreshold), }) return db } // Client returns the Client the Database was created from. func (db Database) Client() Client { return db.client } // Name returns the name of the database. func (db Database) Name() string { return db.name } // Collection gets a handle for a collection with the given name configured with the given CollectionOptions. func (db Database) Collection(name string, opts ...options.CollectionOptions) Collection { return newCollection(db, name, opts...) } // 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 (db Database) Aggregate(ctx context.Context, pipeline interface{}, opts ...options.AggregateOptions) (Cursor, error) { a := aggregateParams{ ctx: ctx, pipeline: pipeline, client: db.client, registry: db.registry, readConcern: db.readConcern, writeConcern: db.writeConcern, retryRead: db.client.retryReads, db: db.name, readSelector: db.readSelector, writeSelector: db.writeSelector, readPreference: db.readPreference, opts: opts, } return aggregate(a) } func (db Database) processRunCommand(ctx context.Context, cmd interface{}, cursorCommand bool, opts ...options.RunCmdOptions) (operation.Command, session.Client, error) { sess := sessionFromContext(ctx) if sess == nil && db.client.sessionPool != nil { sess = session.NewImplicitClientSession(db.client.sessionPool, db.client.id) } err := db.client.validSession(sess) if err != nil { return nil, sess, err } ro := options.MergeRunCmdOptions(append(defaultRunCmdOpts, opts...)...) if sess != nil && sess.TransactionRunning() && ro.ReadPreference != nil && ro.ReadPreference.Mode() != readpref.PrimaryMode { return nil, sess, errors.New("read preference in a transaction must be primary") } if isUnorderedMap(cmd) { return nil, sess, ErrMapForOrderedArgument{"cmd"} } runCmdDoc, err := marshal(cmd, db.bsonOpts, db.registry) if err != nil { return nil, sess, err } readSelect := description.CompositeSelector([]description.ServerSelector{ description.ReadPrefSelector(ro.ReadPreference), description.LatencySelector(db.client.localThreshold), }) if sess != nil && sess.PinnedServer != nil { readSelect = makePinnedSelector(sess, readSelect) } var op operation.Command switch cursorCommand { case true: cursorOpts := db.client.createBaseCursorOptions() cursorOpts.MarshalValueEncoderFn = newEncoderFn(db.bsonOpts, db.registry) op = operation.NewCursorCommand(runCmdDoc, cursorOpts) default: op = operation.NewCommand(runCmdDoc) } return op.Session(sess).CommandMonitor(db.client.monitor). ServerSelector(readSelect).ClusterClock(db.client.clock). Database(db.name).Deployment(db.client.deployment). Crypt(db.client.cryptFLE).ReadPreference(ro.ReadPreference).ServerAPI(db.client.serverAPI). Timeout(db.client.timeout).Logger(db.client.logger), sess, nil } // 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 func (db Database) RunCommand(ctx context.Context, runCommand interface{}, opts ...options.RunCmdOptions) SingleResult { if ctx == nil { ctx = context.Background() } op, sess, err := db.processRunCommand(ctx, runCommand, false, opts...) defer closeImplicitSession(sess) if err != nil { return &SingleResult{err: err} } err = op.Execute(ctx) // RunCommand can be used to run a write, thus execute may return a write error _, convErr := processWriteError(err) return &SingleResult{ ctx: ctx, err: convErr, rdr: bson.Raw(op.Result()), bsonOpts: db.bsonOpts, reg: db.registry, } } // 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 (db Database) RunCommandCursor(ctx context.Context, runCommand interface{}, opts ...options.RunCmdOptions) (Cursor, error) { if ctx == nil { ctx = context.Background() } op, sess, err := db.processRunCommand(ctx, runCommand, true, opts...) if err != nil { closeImplicitSession(sess) return nil, replaceErrors(err) } if err = op.Execute(ctx); err != nil { closeImplicitSession(sess) if errors.Is(err, driver.ErrNoCursor) { return nil, errors.New( "database response does not contain a cursor; try using RunCommand instead") } return nil, replaceErrors(err) } bc, err := op.ResultCursor() if err != nil { closeImplicitSession(sess) return nil, replaceErrors(err) } cursor, err := newCursorWithSession(bc, db.bsonOpts, db.registry, sess) return cursor, replaceErrors(err) } // 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 (db Database) Drop(ctx context.Context) error { if ctx == nil { ctx = context.Background() } sess := sessionFromContext(ctx) if sess == nil && db.client.sessionPool != nil { sess = session.NewImplicitClientSession(db.client.sessionPool, db.client.id) defer sess.EndSession() } err := db.client.validSession(sess) if err != nil { return err } wc := db.writeConcern if sess.TransactionRunning() { wc = nil } if !writeconcern.AckWrite(wc) { sess = nil } selector := makePinnedSelector(sess, db.writeSelector) op := operation.NewDropDatabase(). Session(sess).WriteConcern(wc).CommandMonitor(db.client.monitor). ServerSelector(selector).ClusterClock(db.client.clock). Database(db.name).Deployment(db.client.deployment).Crypt(db.client.cryptFLE). ServerAPI(db.client.serverAPI) err = op.Execute(ctx) driverErr, ok := err.(driver.Error) if err != nil && (!ok \|\| !driverErr.NamespaceNotFound()) { return replaceErrors(err) } return nil } // 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/. // // BUG(benjirewis): ListCollectionSpecifications prevents listing more than 100 collections per database when running // against MongoDB version 2.6. func (db Database) ListCollectionSpecifications(ctx context.Context, filter interface{}, opts ...options.ListCollectionsOptions) ([]CollectionSpecification, error) { cursor, err := db.ListCollections(ctx, filter, opts...) if err != nil { return nil, err } var specs []CollectionSpecification err = cursor.All(ctx, &specs) if err != nil { return nil, err } for _, spec := range specs { // Pre-4.4 servers report a namespace in their responses, so we only set Namespace manually if it was not in // the response. if spec.IDIndex != nil && spec.IDIndex.Namespace == "" { spec.IDIndex.Namespace = db.name + "." + spec.Name } } return specs, nil } // 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 (db Database) ListCollections(ctx context.Context, filter interface{}, opts ...options.ListCollectionsOptions) (Cursor, error) { if ctx == nil { ctx = context.Background() } filterDoc, err := marshal(filter, db.bsonOpts, db.registry) if err != nil { return nil, err } sess := sessionFromContext(ctx) if sess == nil && db.client.sessionPool != nil { sess = session.NewImplicitClientSession(db.client.sessionPool, db.client.id) } err = db.client.validSession(sess) if err != nil { closeImplicitSession(sess) return nil, err } selector := description.CompositeSelector([]description.ServerSelector{ description.ReadPrefSelector(readpref.Primary()), description.LatencySelector(db.client.localThreshold), }) selector = makeReadPrefSelector(sess, selector, db.client.localThreshold) lco := options.MergeListCollectionsOptions(opts...) op := operation.NewListCollections(filterDoc). Session(sess).ReadPreference(db.readPreference).CommandMonitor(db.client.monitor). ServerSelector(selector).ClusterClock(db.client.clock). Database(db.name).Deployment(db.client.deployment).Crypt(db.client.cryptFLE). ServerAPI(db.client.serverAPI).Timeout(db.client.timeout) cursorOpts := db.client.createBaseCursorOptions() cursorOpts.MarshalValueEncoderFn = newEncoderFn(db.bsonOpts, db.registry) if lco.NameOnly != nil { op = op.NameOnly(lco.NameOnly) } if lco.BatchSize != nil { cursorOpts.BatchSize = lco.BatchSize op = op.BatchSize(lco.BatchSize) } if lco.AuthorizedCollections != nil { op = op.AuthorizedCollections(lco.AuthorizedCollections) } retry := driver.RetryNone if db.client.retryReads { retry = driver.RetryOncePerCommand } op = op.Retry(retry) err = op.Execute(ctx) if err != nil { closeImplicitSession(sess) return nil, replaceErrors(err) } bc, err := op.Result(cursorOpts) if err != nil { closeImplicitSession(sess) return nil, replaceErrors(err) } cursor, err := newCursorWithSession(bc, db.bsonOpts, db.registry, sess) return cursor, replaceErrors(err) } // 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. func (db Database) ListCollectionNames(ctx context.Context, filter interface{}, opts ...options.ListCollectionsOptions) ([]string, error) { opts = append(opts, options.ListCollections().SetNameOnly(true)) res, err := db.ListCollections(ctx, filter, opts...) if err != nil { return nil, err } defer res.Close(ctx) names := make([]string, 0) for res.Next(ctx) { elem, err := res.Current.LookupErr("name") if err != nil { return nil, err } if elem.Type != bson.TypeString { return nil, fmt.Errorf("incorrect type for 'name'. got %v. want %v", elem.Type, bson.TypeString) } elemName := elem.StringValue() names = append(names, elemName) } res.Close(ctx) return names, nil } // ReadConcern returns the read concern used to configure the Database object. func (db Database) ReadConcern() readconcern.ReadConcern { return db.readConcern } // ReadPreference returns the read preference used to configure the Database object. func (db Database) ReadPreference() readpref.ReadPref { return db.readPreference } // WriteConcern returns the write concern used to configure the Database object. func (db Database) WriteConcern() writeconcern.WriteConcern { return db.writeConcern } // 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). func (db Database) Watch(ctx context.Context, pipeline interface{}, opts ...options.ChangeStreamOptions) (ChangeStream, error) { csConfig := changeStreamConfig{ readConcern: db.readConcern, readPreference: db.readPreference, client: db.client, registry: db.registry, streamType: DatabaseStream, databaseName: db.Name(), crypt: db.client.cryptFLE, } return newChangeStream(ctx, csConfig, pipeline, opts...) } // 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/. func (db Database) CreateCollection(ctx context.Context, name string, opts ...options.CreateCollectionOptions) error { cco := options.MergeCreateCollectionOptions(opts...) // Follow Client-Side Encryption specification to check for encryptedFields. // Check for encryptedFields from create options. ef := cco.EncryptedFields // Check for encryptedFields from the client EncryptedFieldsMap. if ef == nil { ef = db.getEncryptedFieldsFromMap(name) } if ef != nil { return db.createCollectionWithEncryptedFields(ctx, name, ef, opts...) } return db.createCollection(ctx, name, opts...) } // getEncryptedFieldsFromServer tries to get an "encryptedFields" document associated with collectionName by running the "listCollections" command. // Returns nil and no error if the listCollections command succeeds, but "encryptedFields" is not present. func (db Database) getEncryptedFieldsFromServer(ctx context.Context, collectionName string) (interface{}, error) { // Check if collection has an EncryptedFields configured server-side. collSpecs, err := db.ListCollectionSpecifications(ctx, bson.D{{"name", collectionName}}) if err != nil { return nil, err } if len(collSpecs) == 0 { return nil, nil } if len(collSpecs) > 1 { return nil, fmt.Errorf("expected 1 or 0 results from listCollections, got %v", len(collSpecs)) } collSpec := collSpecs[0] rawValue, err := collSpec.Options.LookupErr("encryptedFields") if errors.Is(err, bsoncore.ErrElementNotFound) { return nil, nil } else if err != nil { return nil, err } encryptedFields, ok := rawValue.DocumentOK() if !ok { return nil, fmt.Errorf("expected encryptedFields of %v to be document, got %v", collectionName, rawValue.Type) } return encryptedFields, nil } // getEncryptedFieldsFromServer tries to get an "encryptedFields" document associated with collectionName by checking the client EncryptedFieldsMap. // Returns nil and no error if an EncryptedFieldsMap is not configured, or does not contain an entry for collectionName. func (db Database) getEncryptedFieldsFromMap(collectionName string) interface{} { // Check the EncryptedFieldsMap efMap := db.client.encryptedFieldsMap if efMap == nil { return nil } namespace := db.name + "." + collectionName ef, ok := efMap[namespace] if ok { return ef } return nil } // createCollectionWithEncryptedFields creates a collection with an EncryptedFields. func (db Database) createCollectionWithEncryptedFields(ctx context.Context, name string, ef interface{}, opts ...options.CreateCollectionOptions) error { efBSON, err := marshal(ef, db.bsonOpts, db.registry) if err != nil { return fmt.Errorf("error transforming document: %w", err) } // Check the wire version to ensure server is 7.0.0 or newer. // After the wire version check, and before creating the collections, it is possible the server state changes. // That is OK. This wire version check is a best effort to inform users earlier if using a QEv2 driver with a QEv1 server. { const QEv2WireVersion = 21 server, err := db.client.deployment.SelectServer(ctx, description.WriteSelector()) if err != nil { return fmt.Errorf("error selecting server to check maxWireVersion: %w", err) } conn, err := server.Connection(ctx) if err != nil { return fmt.Errorf("error getting connection to check maxWireVersion: %w", err) } defer conn.Close() wireVersionRange := conn.Description().WireVersion if wireVersionRange.Max < QEv2WireVersion { return fmt.Errorf("Driver support of Queryable Encryption is incompatible with server. Upgrade server to use Queryable Encryption. Got maxWireVersion %v but need maxWireVersion >= %v", wireVersionRange.Max, QEv2WireVersion) } } // Create the two encryption-related, associated collections: `escCollection` and `ecocCollection`. stateCollectionOpts := options.CreateCollection(). SetClusteredIndex(bson.D{{"key", bson.D{{"_id", 1}}}, {"unique", true}}) // Create ESCCollection. escCollection, err := csfle.GetEncryptedStateCollectionName(efBSON, name, csfle.EncryptedStateCollection) if err != nil { return err } if err := db.createCollection(ctx, escCollection, stateCollectionOpts); err != nil { return err } // Create ECOCCollection. ecocCollection, err := csfle.GetEncryptedStateCollectionName(efBSON, name, csfle.EncryptedCompactionCollection) if err != nil { return err } if err := db.createCollection(ctx, ecocCollection, stateCollectionOpts); err != nil { return err } // Create a data collection with the 'encryptedFields' option. op, err := db.createCollectionOperation(name, opts...) if err != nil { return err } op.EncryptedFields(efBSON) if err := db.executeCreateOperation(ctx, op); err != nil { return err } // Create an index on the __safeContent__ field in the collection @collectionName. if _, err := db.Collection(name).Indexes().CreateOne(ctx, IndexModel{Keys: bson.D{{"__safeContent__", 1}}}); err != nil { return fmt.Errorf("error creating safeContent index: %w", err) } return nil } // createCollection creates a collection without EncryptedFields. func (db Database) createCollection(ctx context.Context, name string, opts ...options.CreateCollectionOptions) error { op, err := db.createCollectionOperation(name, opts...) if err != nil { return err } return db.executeCreateOperation(ctx, op) } func (db Database) createCollectionOperation(name string, opts ...options.CreateCollectionOptions) (operation.Create, error) { cco := options.MergeCreateCollectionOptions(opts...) op := operation.NewCreate(name).ServerAPI(db.client.serverAPI) if cco.Capped != nil { op.Capped(cco.Capped) } if cco.Collation != nil { op.Collation(bsoncore.Document(cco.Collation.ToDocument())) } if cco.ChangeStreamPreAndPostImages != nil { csppi, err := marshal(cco.ChangeStreamPreAndPostImages, db.bsonOpts, db.registry) if err != nil { return nil, err } op.ChangeStreamPreAndPostImages(csppi) } if cco.DefaultIndexOptions != nil { idx, doc := bsoncore.AppendDocumentStart(nil) if cco.DefaultIndexOptions.StorageEngine != nil { storageEngine, err := marshal(cco.DefaultIndexOptions.StorageEngine, db.bsonOpts, db.registry) if err != nil { return nil, err } doc = bsoncore.AppendDocumentElement(doc, "storageEngine", storageEngine) } doc, err := bsoncore.AppendDocumentEnd(doc, idx) if err != nil { return nil, err } op.IndexOptionDefaults(doc) } if cco.MaxDocuments != nil { op.Max(cco.MaxDocuments) } if cco.SizeInBytes != nil { op.Size(cco.SizeInBytes) } if cco.StorageEngine != nil { storageEngine, err := marshal(cco.StorageEngine, db.bsonOpts, db.registry) if err != nil { return nil, err } op.StorageEngine(storageEngine) } if cco.ValidationAction != nil { op.ValidationAction(cco.ValidationAction) } if cco.ValidationLevel != nil { op.ValidationLevel(cco.ValidationLevel) } if cco.Validator != nil { validator, err := marshal(cco.Validator, db.bsonOpts, db.registry) if err != nil { return nil, err } op.Validator(validator) } if cco.ExpireAfterSeconds != nil { op.ExpireAfterSeconds(cco.ExpireAfterSeconds) } if cco.TimeSeriesOptions != nil { idx, doc := bsoncore.AppendDocumentStart(nil) doc = bsoncore.AppendStringElement(doc, "timeField", cco.TimeSeriesOptions.TimeField) if cco.TimeSeriesOptions.MetaField != nil { doc = bsoncore.AppendStringElement(doc, "metaField", cco.TimeSeriesOptions.MetaField) } if cco.TimeSeriesOptions.Granularity != nil { doc = bsoncore.AppendStringElement(doc, "granularity", cco.TimeSeriesOptions.Granularity) } if cco.TimeSeriesOptions.BucketMaxSpan != nil { bmss := int64(cco.TimeSeriesOptions.BucketMaxSpan / time.Second) doc = bsoncore.AppendInt64Element(doc, "bucketMaxSpanSeconds", bmss) } if cco.TimeSeriesOptions.BucketRounding != nil { brs := int64(cco.TimeSeriesOptions.BucketRounding / time.Second) doc = bsoncore.AppendInt64Element(doc, "bucketRoundingSeconds", brs) } doc, err := bsoncore.AppendDocumentEnd(doc, idx) if err != nil { return nil, err } op.TimeSeries(doc) } if cco.ClusteredIndex != nil { clusteredIndex, err := marshal(cco.ClusteredIndex, db.bsonOpts, db.registry) if err != nil { return nil, err } op.ClusteredIndex(clusteredIndex) } return op, nil } // 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). func (db Database) CreateView(ctx context.Context, viewName, viewOn string, pipeline interface{}, opts ...options.CreateViewOptions) error { pipelineArray, _, err := marshalAggregatePipeline(pipeline, db.bsonOpts, db.registry) if err != nil { return err } op := operation.NewCreate(viewName). ViewOn(viewOn). Pipeline(pipelineArray). ServerAPI(db.client.serverAPI) cvo := options.MergeCreateViewOptions(opts...) if cvo.Collation != nil { op.Collation(bsoncore.Document(cvo.Collation.ToDocument())) } return db.executeCreateOperation(ctx, op) } func (db Database) executeCreateOperation(ctx context.Context, op operation.Create) error { sess := sessionFromContext(ctx) if sess == nil && db.client.sessionPool != nil { sess = session.NewImplicitClientSession(db.client.sessionPool, db.client.id) defer sess.EndSession() } err := db.client.validSession(sess) if err != nil { return err } wc := db.writeConcern if sess.TransactionRunning() { wc = nil } if !writeconcern.AckWrite(wc) { sess = nil } selector := makePinnedSelector(sess, db.writeSelector) op = op.Session(sess). WriteConcern(wc). CommandMonitor(db.client.monitor). ServerSelector(selector). ClusterClock(db.client.clock). Database(db.name). Deployment(db.client.deployment). Crypt(db.client.cryptFLE) return replaceErrors(op.Execute(ctx)) }	28.85 KB	2025-05-25 12:27
📄 database_test.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "context" "errors" "testing" "time" "go.mongodb.org/mongo-driver/bson" "go.mongodb.org/mongo-driver/bson/bsoncodec" "go.mongodb.org/mongo-driver/internal/assert" "go.mongodb.org/mongo-driver/mongo/options" "go.mongodb.org/mongo-driver/mongo/readconcern" "go.mongodb.org/mongo-driver/mongo/readpref" "go.mongodb.org/mongo-driver/mongo/writeconcern" "go.mongodb.org/mongo-driver/x/mongo/driver/topology" ) func setupDb(name string, opts ...options.DatabaseOptions) Database { client := setupClient() return client.Database(name, opts...) } func compareDbs(t testing.T, expected, got Database) { t.Helper() assert.Equal(t, expected.readPreference, got.readPreference, "expected read preference %v, got %v", expected.readPreference, got.readPreference) assert.Equal(t, expected.readConcern, got.readConcern, "expected read concern %v, got %v", expected.readConcern, got.readConcern) assert.Equal(t, expected.writeConcern, got.writeConcern, "expected write concern %v, got %v", expected.writeConcern, got.writeConcern) assert.Equal(t, expected.registry, got.registry, "expected write concern %v, got %v", expected.registry, got.registry) } func TestDatabase(t testing.T) { t.Run("initialize", func(t testing.T) { name := "foo" db := setupDb(name) assert.Equal(t, name, db.Name(), "expected db name %v, got %v", name, db.Name()) assert.NotNil(t, db.Client(), "expected valid client, got nil") }) t.Run("options", func(t testing.T) { t.Run("custom", func(t testing.T) { rpPrimary := readpref.Primary() rpSecondary := readpref.Secondary() wc1 := writeconcern.New(writeconcern.W(5)) wc2 := writeconcern.New(writeconcern.W(10)) rcLocal := readconcern.Local() rcMajority := readconcern.Majority() reg := bsoncodec.NewRegistryBuilder().Build() opts := options.Database().SetReadPreference(rpPrimary).SetReadConcern(rcLocal).SetWriteConcern(wc1). SetReadPreference(rpSecondary).SetReadConcern(rcMajority).SetWriteConcern(wc2).SetRegistry(reg) expected := &Database{ readPreference: rpSecondary, readConcern: rcMajority, writeConcern: wc2, registry: reg, } got := setupDb("foo", opts) compareDbs(t, expected, got) }) t.Run("inherit", func(t testing.T) { rpPrimary := readpref.Primary() rcLocal := readconcern.Local() wc1 := writeconcern.New(writeconcern.W(10)) reg := bsoncodec.NewRegistryBuilder().Build() client := setupClient(options.Client().SetReadPreference(rpPrimary).SetReadConcern(rcLocal).SetRegistry(reg)) got := client.Database("foo", options.Database().SetWriteConcern(wc1)) expected := &Database{ readPreference: rpPrimary, readConcern: rcLocal, writeConcern: wc1, registry: reg, } compareDbs(t, expected, got) }) }) t.Run("replace topology error", func(t testing.T) { db := setupDb("foo") err := db.RunCommand(bgCtx, bson.D{{"x", 1}}).Err() assert.Equal(t, ErrClientDisconnected, err, "expected error %v, got %v", ErrClientDisconnected, err) err = db.Drop(bgCtx) assert.Equal(t, ErrClientDisconnected, err, "expected error %v, got %v", ErrClientDisconnected, err) _, err = db.ListCollections(bgCtx, bson.D{}) assert.Equal(t, ErrClientDisconnected, err, "expected error %v, got %v", ErrClientDisconnected, err) }) t.Run("TransientTransactionError label", func(t testing.T) { client := setupClient(options.Client().ApplyURI("mongodb://nonexistent").SetServerSelectionTimeout(3 time.Second)) err := client.Connect(bgCtx) defer func() { _ = client.Disconnect(bgCtx) }() assert.Nil(t, err, "expected nil, got %v", err) t.Run("negative case of non-transaction", func(t testing.T) { var sse topology.ServerSelectionError var le LabeledError err := client.Ping(bgCtx, nil) assert.NotNil(t, err, "expected error, got nil") assert.True(t, errors.As(err, &sse), `expected error to be a "topology.ServerSelectionError"`) if errors.As(err, &le) { assert.False(t, le.HasErrorLabel("TransientTransactionError"), `expected error not to include the "TransientTransactionError" label`) } }) t.Run("positive case of transaction", func(t testing.T) { var sse topology.ServerSelectionError var le LabeledError sess, err := client.StartSession() assert.Nil(t, err, "expected nil, got %v", err) defer sess.EndSession(bgCtx) sessCtx := NewSessionContext(bgCtx, sess) err = sess.StartTransaction() assert.Nil(t, err, "expected nil, got %v", err) err = client.Ping(sessCtx, nil) assert.NotNil(t, err, "expected error, got nil") assert.True(t, errors.As(err, &sse), `expected error to be a "topology.ServerSelectionError"`) assert.True(t, errors.As(err, &le), `expected error to implement the "LabeledError" interface`) assert.True(t, le.HasErrorLabel("TransientTransactionError"), `expected error to include the "TransientTransactionError" label`) }) }) t.Run("nil document error", func(t *testing.T) { db := setupDb("foo") err := db.RunCommand(bgCtx, nil).Err() assert.Equal(t, ErrNilDocument, err, "expected error %v, got %v", ErrNilDocument, err) _, err = db.Watch(context.Background(), nil) watchErr := errors.New("can only marshal slices and arrays into aggregation pipelines, but got invalid") assert.Equal(t, watchErr, err, "expected error %v, got %v", watchErr, err) _, err = db.ListCollections(context.Background(), nil) assert.Equal(t, ErrNilDocument, err, "expected error %v, got %v", ErrNilDocument, err) _, err = db.ListCollectionNames(context.Background(), nil) assert.Equal(t, ErrNilDocument, err, "expected error %v, got %v", ErrNilDocument, err) }) }	5.82 KB	2025-05-25 12:27
📁 description	-	2025-05-25 12:27
📄 doc.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 // NOTE: This documentation should be kept in line with the Example* test functions. // 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(), 20time.Second) // defer cancel() // client, err := mongo.Connect(ctx, 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 package mongo	6.31 KB	2025-05-25 12:27
📄 errors.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "bytes" "context" "errors" "fmt" "net" "strings" "go.mongodb.org/mongo-driver/bson" "go.mongodb.org/mongo-driver/internal/codecutil" "go.mongodb.org/mongo-driver/x/mongo/driver" "go.mongodb.org/mongo-driver/x/mongo/driver/mongocrypt" "go.mongodb.org/mongo-driver/x/mongo/driver/topology" ) // ErrUnacknowledgedWrite is returned by operations that have an unacknowledged write concern. var ErrUnacknowledgedWrite = errors.New("unacknowledged write") // ErrClientDisconnected is returned when disconnected Client is used to run an operation. var ErrClientDisconnected = errors.New("client is disconnected") // ErrNilDocument is returned when a nil document is passed to a CRUD method. var ErrNilDocument = errors.New("document is nil") // ErrNilValue is returned when a nil value is passed to a CRUD method. var ErrNilValue = errors.New("value is nil") // ErrEmptySlice is returned when an empty slice is passed to a CRUD method that requires a non-empty slice. var ErrEmptySlice = errors.New("must provide at least one element in input slice") // ErrMapForOrderedArgument is returned when a map with multiple keys is passed to a CRUD method for an ordered parameter type ErrMapForOrderedArgument struct { ParamName string } // Error implements the error interface. func (e ErrMapForOrderedArgument) Error() string { return fmt.Sprintf("multi-key map passed in for ordered parameter %v", e.ParamName) } func replaceErrors(err error) error { // Return nil when err is nil to avoid costly reflection logic below. if err == nil { return nil } if errors.Is(err, topology.ErrTopologyClosed) { return ErrClientDisconnected } if de, ok := err.(driver.Error); ok { return CommandError{ Code: de.Code, Message: de.Message, Labels: de.Labels, Name: de.Name, Wrapped: de.Wrapped, Raw: bson.Raw(de.Raw), } } if qe, ok := err.(driver.QueryFailureError); ok { // qe.Message is "command failure" ce := CommandError{ Name: qe.Message, Wrapped: qe.Wrapped, Raw: bson.Raw(qe.Response), } dollarErr, err := qe.Response.LookupErr("$err") if err == nil { ce.Message, _ = dollarErr.StringValueOK() } code, err := qe.Response.LookupErr("code") if err == nil { ce.Code, _ = code.Int32OK() } return ce } if me, ok := err.(mongocrypt.Error); ok { return MongocryptError{Code: me.Code, Message: me.Message} } if errors.Is(err, codecutil.ErrNilValue) { return ErrNilValue } if marshalErr, ok := err.(codecutil.MarshalError); ok { return MarshalError{ Value: marshalErr.Value, Err: marshalErr.Err, } } return err } // IsDuplicateKeyError returns true if err is a duplicate key error. func IsDuplicateKeyError(err error) bool { if se := ServerError(nil); errors.As(err, &se) { return se.HasErrorCode(11000) \|\| // Duplicate key error. se.HasErrorCode(11001) \|\| // Duplicate key error on update. // Duplicate key error in a capped collection. See SERVER-7164. se.HasErrorCode(12582) \|\| // Mongos insert error caused by a duplicate key error. See // SERVER-11493. se.HasErrorCodeWithMessage(16460, " E11000 ") } return false } // timeoutErrs is a list of error values that indicate a timeout happened. var timeoutErrs = [...]error{ context.DeadlineExceeded, driver.ErrDeadlineWouldBeExceeded, topology.ErrServerSelectionTimeout, } // 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 IsTimeout(err error) bool { // Check if the error chain contains any of the timeout error values. for _, target := range timeoutErrs { if errors.Is(err, target) { return true } } // Check if the error chain contains any error types that can indicate // timeout. if errors.As(err, &topology.WaitQueueTimeoutError{}) { return true } if ce := (CommandError{}); errors.As(err, &ce) && ce.IsMaxTimeMSExpiredError() { return true } if we := (WriteException{}); errors.As(err, &we) && we.WriteConcernError != nil && we.WriteConcernError.IsMaxTimeMSExpiredError() { return true } if ne := net.Error(nil); errors.As(err, &ne) { return ne.Timeout() } // Check timeout error labels. if le := LabeledError(nil); errors.As(err, &le) { if le.HasErrorLabel("NetworkTimeoutError") \|\| le.HasErrorLabel("ExceededTimeLimitError") { return true } } return false } // unwrap returns the inner error if err implements Unwrap(), otherwise it returns nil. func unwrap(err error) error { u, ok := err.(interface { Unwrap() error }) if !ok { return nil } return u.Unwrap() } // errorHasLabel returns true if err contains the specified label func errorHasLabel(err error, label string) bool { for ; err != nil; err = unwrap(err) { if le, ok := err.(LabeledError); ok && le.HasErrorLabel(label) { return true } } return false } // IsNetworkError returns true if err is a network error func IsNetworkError(err error) bool { return errorHasLabel(err, "NetworkError") } // MongocryptError represents an libmongocrypt error during client-side encryption. type MongocryptError struct { Code int32 Message string } // Error implements the error interface. func (m MongocryptError) Error() string { return fmt.Sprintf("mongocrypt error %d: %v", m.Code, m.Message) } // EncryptionKeyVaultError represents an error while communicating with the key vault collection during client-side // encryption. type EncryptionKeyVaultError struct { Wrapped error } // Error implements the error interface. func (ekve EncryptionKeyVaultError) Error() string { return fmt.Sprintf("key vault communication error: %v", ekve.Wrapped) } // Unwrap returns the underlying error. func (ekve EncryptionKeyVaultError) Unwrap() error { return ekve.Wrapped } // MongocryptdError represents an error while communicating with mongocryptd during client-side encryption. type MongocryptdError struct { Wrapped error } // Error implements the error interface. func (e MongocryptdError) Error() string { return fmt.Sprintf("mongocryptd communication error: %v", e.Wrapped) } // Unwrap returns the underlying error. func (e MongocryptdError) Unwrap() error { return e.Wrapped } // LabeledError is an interface for errors with labels. type LabeledError interface { error // HasErrorLabel returns true if the error contains the specified label. HasErrorLabel(string) bool } // ServerError is the interface implemented by errors returned from the server. Custom implementations of this // interface should not be used in production. 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 serverError() } var _ ServerError = CommandError{} var _ ServerError = WriteError{} var _ ServerError = WriteException{} var _ ServerError = BulkWriteException{} // CommandError represents a server error during execution of a command. This can be returned by any operation. 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. } // Error implements the error interface. func (e CommandError) Error() string { if e.Name != "" { return fmt.Sprintf("(%v) %v", e.Name, e.Message) } return e.Message } // Unwrap returns the underlying error. func (e CommandError) Unwrap() error { return e.Wrapped } // HasErrorCode returns true if the error has the specified code. func (e CommandError) HasErrorCode(code int) bool { return int(e.Code) == code } // HasErrorLabel returns true if the error contains the specified label. func (e CommandError) HasErrorLabel(label string) bool { if e.Labels != nil { for _, l := range e.Labels { if l == label { return true } } } return false } // HasErrorMessage returns true if the error contains the specified message. func (e CommandError) HasErrorMessage(message string) bool { return strings.Contains(e.Message, message) } // HasErrorCodeWithMessage returns true if the error has the specified code and Message contains the specified message. func (e CommandError) HasErrorCodeWithMessage(code int, message string) bool { return int(e.Code) == code && strings.Contains(e.Message, message) } // IsMaxTimeMSExpiredError returns true if the error is a MaxTimeMSExpired error. func (e CommandError) IsMaxTimeMSExpiredError() bool { return e.Code == 50 \|\| e.Name == "MaxTimeMSExpired" } // serverError implements the ServerError interface. func (e CommandError) serverError() {} // 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. 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 } func (we WriteError) Error() string { msg := we.Message if len(we.Details) > 0 { msg = fmt.Sprintf("%s: %s", msg, we.Details.String()) } return msg } // HasErrorCode returns true if the error has the specified code. func (we WriteError) HasErrorCode(code int) bool { return we.Code == code } // HasErrorLabel returns true if the error contains the specified label. WriteErrors do not contain labels, // so we always return false. func (we WriteError) HasErrorLabel(string) bool { return false } // HasErrorMessage returns true if the error contains the specified message. func (we WriteError) HasErrorMessage(message string) bool { return strings.Contains(we.Message, message) } // HasErrorCodeWithMessage returns true if the error has the specified code and Message contains the specified message. func (we WriteError) HasErrorCodeWithMessage(code int, message string) bool { return we.Code == code && strings.Contains(we.Message, message) } // serverError implements the ServerError interface. func (we WriteError) serverError() {} // WriteErrors is a group of write errors that occurred during execution of a write operation. type WriteErrors []WriteError // Error implements the error interface. func (we WriteErrors) Error() string { errs := make([]error, len(we)) for i := 0; i < len(we); i++ { errs[i] = we[i] } // WriteErrors isn't returned from batch operations, but we can still use the same formatter. return "write errors: " + joinBatchErrors(errs) } func writeErrorsFromDriverWriteErrors(errs driver.WriteErrors) WriteErrors { wes := make(WriteErrors, 0, len(errs)) for _, err := range errs { wes = append(wes, WriteError{ Index: int(err.Index), Code: int(err.Code), Message: err.Message, Details: bson.Raw(err.Details), Raw: bson.Raw(err.Raw), }) } return wes } // 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. type WriteConcernError struct { Name string Code int Message string Details bson.Raw Raw bson.Raw // The original write concern error from the server response. } // Error implements the error interface. func (wce WriteConcernError) Error() string { if wce.Name != "" { return fmt.Sprintf("(%v) %v", wce.Name, wce.Message) } return wce.Message } // IsMaxTimeMSExpiredError returns true if the error is a MaxTimeMSExpired error. func (wce WriteConcernError) IsMaxTimeMSExpiredError() bool { return wce.Code == 50 } // WriteException is the error type returned by the InsertOne, DeleteOne, DeleteMany, UpdateOne, UpdateMany, and // ReplaceOne operations. 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 } // Error implements the error interface. func (mwe WriteException) Error() string { causes := make([]string, 0, 2) if mwe.WriteConcernError != nil { causes = append(causes, "write concern error: "+mwe.WriteConcernError.Error()) } if len(mwe.WriteErrors) > 0 { // The WriteErrors error message already starts with "write errors:", so don't add it to the // error message again. causes = append(causes, mwe.WriteErrors.Error()) } message := "write exception: " if len(causes) == 0 { return message + "no causes" } return message + strings.Join(causes, ", ") } // HasErrorCode returns true if the error has the specified code. func (mwe WriteException) HasErrorCode(code int) bool { if mwe.WriteConcernError != nil && mwe.WriteConcernError.Code == code { return true } for _, we := range mwe.WriteErrors { if we.Code == code { return true } } return false } // HasErrorLabel returns true if the error contains the specified label. func (mwe WriteException) HasErrorLabel(label string) bool { if mwe.Labels != nil { for _, l := range mwe.Labels { if l == label { return true } } } return false } // HasErrorMessage returns true if the error contains the specified message. func (mwe WriteException) HasErrorMessage(message string) bool { if mwe.WriteConcernError != nil && strings.Contains(mwe.WriteConcernError.Message, message) { return true } for _, we := range mwe.WriteErrors { if strings.Contains(we.Message, message) { return true } } return false } // HasErrorCodeWithMessage returns true if any of the contained errors have the specified code and message. func (mwe WriteException) HasErrorCodeWithMessage(code int, message string) bool { if mwe.WriteConcernError != nil && mwe.WriteConcernError.Code == code && strings.Contains(mwe.WriteConcernError.Message, message) { return true } for _, we := range mwe.WriteErrors { if we.Code == code && strings.Contains(we.Message, message) { return true } } return false } // serverError implements the ServerError interface. func (mwe WriteException) serverError() {} func convertDriverWriteConcernError(wce driver.WriteConcernError) WriteConcernError { if wce == nil { return nil } return &WriteConcernError{ Name: wce.Name, Code: int(wce.Code), Message: wce.Message, Details: bson.Raw(wce.Details), Raw: bson.Raw(wce.Raw), } } // 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. type BulkWriteError struct { WriteError // The WriteError that occurred. Request WriteModel // The WriteModel that caused this error. } // Error implements the error interface. func (bwe BulkWriteError) Error() string { return bwe.WriteError.Error() } // BulkWriteException is the error type returned by BulkWrite and InsertMany operations. 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 } // Error implements the error interface. func (bwe BulkWriteException) Error() string { causes := make([]string, 0, 2) if bwe.WriteConcernError != nil { causes = append(causes, "write concern error: "+bwe.WriteConcernError.Error()) } if len(bwe.WriteErrors) > 0 { errs := make([]error, len(bwe.WriteErrors)) for i := 0; i < len(bwe.WriteErrors); i++ { errs[i] = &bwe.WriteErrors[i] } causes = append(causes, "write errors: "+joinBatchErrors(errs)) } message := "bulk write exception: " if len(causes) == 0 { return message + "no causes" } return "bulk write exception: " + strings.Join(causes, ", ") } // HasErrorCode returns true if any of the errors have the specified code. func (bwe BulkWriteException) HasErrorCode(code int) bool { if bwe.WriteConcernError != nil && bwe.WriteConcernError.Code == code { return true } for _, we := range bwe.WriteErrors { if we.Code == code { return true } } return false } // HasErrorLabel returns true if the error contains the specified label. func (bwe BulkWriteException) HasErrorLabel(label string) bool { if bwe.Labels != nil { for _, l := range bwe.Labels { if l == label { return true } } } return false } // HasErrorMessage returns true if the error contains the specified message. func (bwe BulkWriteException) HasErrorMessage(message string) bool { if bwe.WriteConcernError != nil && strings.Contains(bwe.WriteConcernError.Message, message) { return true } for _, we := range bwe.WriteErrors { if strings.Contains(we.Message, message) { return true } } return false } // HasErrorCodeWithMessage returns true if any of the contained errors have the specified code and message. func (bwe BulkWriteException) HasErrorCodeWithMessage(code int, message string) bool { if bwe.WriteConcernError != nil && bwe.WriteConcernError.Code == code && strings.Contains(bwe.WriteConcernError.Message, message) { return true } for _, we := range bwe.WriteErrors { if we.Code == code && strings.Contains(we.Message, message) { return true } } return false } // serverError implements the ServerError interface. func (bwe BulkWriteException) serverError() {} // returnResult is used to determine if a function calling processWriteError should return // the result or return nil. Since the processWriteError function is used by many different // methods, both One and Many, we need a way to differentiate if the method should return // the result and the error. type returnResult int const ( rrNone returnResult = 1 << iota // None means do not return the result ever. rrOne // One means return the result if this was called by a One method. rrMany // Many means return the result is this was called by a Many method. rrAll returnResult = rrOne \| rrMany // All means always return the result. ) // processWriteError handles processing the result of a write operation. If the retrunResult matches // the calling method's type, it should return the result object in addition to the error. // This function will wrap the errors from other packages and return them as errors from this package. // // WriteConcernError will be returned over WriteErrors if both are present. func processWriteError(err error) (returnResult, error) { switch { case errors.Is(err, driver.ErrUnacknowledgedWrite): return rrAll, ErrUnacknowledgedWrite case err != nil: switch tt := err.(type) { case driver.WriteCommandError: return rrMany, WriteException{ WriteConcernError: convertDriverWriteConcernError(tt.WriteConcernError), WriteErrors: writeErrorsFromDriverWriteErrors(tt.WriteErrors), Labels: tt.Labels, Raw: bson.Raw(tt.Raw), } default: return rrNone, replaceErrors(err) } default: return rrAll, nil } } // batchErrorsTargetLength is the target length of error messages returned by batch operation // error types. Try to limit batch error messages to 2kb to prevent problems when printing error // messages from large batch operations. const batchErrorsTargetLength = 2000 // joinBatchErrors appends messages from the given errors to a comma-separated string. If the // string exceeds 2kb, it stops appending error messages and appends the message "+N more errors..." // to the end. // // Example format: // // "[message 1, message 2, +8 more errors...]" func joinBatchErrors(errs []error) string { var buf bytes.Buffer fmt.Fprint(&buf, "[") for idx, err := range errs { if idx != 0 { fmt.Fprint(&buf, ", ") } // If the error message has exceeded the target error message length, stop appending errors // to the message and append the number of remaining errors instead. if buf.Len() > batchErrorsTargetLength { fmt.Fprintf(&buf, "+%d more errors...", len(errs)-idx) break } fmt.Fprint(&buf, err.Error()) } fmt.Fprint(&buf, "]") return buf.String() }	20.42 KB	2025-05-25 12:27
📄 errors_test.go // Copyright (C) MongoDB, Inc. 2022-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "testing" "go.mongodb.org/mongo-driver/bson" "go.mongodb.org/mongo-driver/internal/assert" "go.mongodb.org/mongo-driver/internal/require" ) func TestErrorMessages(t testing.T) { details, err := bson.Marshal(bson.D{{"details", bson.D{{"operatorName", "$jsonSchema"}}}}) require.Nil(t, err, "unexpected error marshaling BSON") cases := []struct { desc string err error expected string }{ { desc: "WriteException error message should contain the WriteError Message and Details", err: WriteException{ WriteErrors: WriteErrors{ { Message: "test message 1", Details: details, }, { Message: "test message 2", Details: details, }, }, }, expected: `write exception: write errors: [test message 1: {"details": {"operatorName": "$jsonSchema"}}, test message 2: {"details": {"operatorName": "$jsonSchema"}}]`, }, { desc: "BulkWriteException error message should contain the WriteError Message and Details", err: BulkWriteException{ WriteErrors: []BulkWriteError{ { WriteError: WriteError{ Message: "test message 1", Details: details, }, }, { WriteError: WriteError{ Message: "test message 2", Details: details, }, }, }, }, expected: `bulk write exception: write errors: [test message 1: {"details": {"operatorName": "$jsonSchema"}}, test message 2: {"details": {"operatorName": "$jsonSchema"}}]`, }, } for _, tc := range cases { tc := tc t.Run(tc.desc, func(t testing.T) { t.Parallel() assert.Equal(t, tc.expected, tc.err.Error()) }) } }	1.88 KB	2025-05-25 12:27
📁 gridfs	-	2025-05-25 12:27
📄 index_options_builder.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "go.mongodb.org/mongo-driver/bson" ) // IndexOptionsBuilder specifies options for a new index. // // Deprecated: Use the IndexOptions type in the mongo/options package instead. type IndexOptionsBuilder struct { document bson.D } // NewIndexOptionsBuilder creates a new IndexOptionsBuilder. // // Deprecated: Use the Index function in mongo/options instead. func NewIndexOptionsBuilder() IndexOptionsBuilder { return &IndexOptionsBuilder{} } // Background specifies a value for the background option. // // Deprecated: Use the IndexOptions.SetBackground function in mongo/options instead. func (iob IndexOptionsBuilder) Background(background bool) IndexOptionsBuilder { iob.document = append(iob.document, bson.E{"background", background}) return iob } // ExpireAfterSeconds specifies a value for the expireAfterSeconds option. // // Deprecated: Use the IndexOptions.SetExpireAfterSeconds function in mongo/options instead. func (iob IndexOptionsBuilder) ExpireAfterSeconds(expireAfterSeconds int32) IndexOptionsBuilder { iob.document = append(iob.document, bson.E{"expireAfterSeconds", expireAfterSeconds}) return iob } // Name specifies a value for the name option. // // Deprecated: Use the IndexOptions.SetName function in mongo/options instead. func (iob IndexOptionsBuilder) Name(name string) IndexOptionsBuilder { iob.document = append(iob.document, bson.E{"name", name}) return iob } // Sparse specifies a value for the sparse option. // // Deprecated: Use the IndexOptions.SetSparse function in mongo/options instead. func (iob IndexOptionsBuilder) Sparse(sparse bool) IndexOptionsBuilder { iob.document = append(iob.document, bson.E{"sparse", sparse}) return iob } // StorageEngine specifies a value for the storageEngine option. // // Deprecated: Use the IndexOptions.SetStorageEngine function in mongo/options instead. func (iob IndexOptionsBuilder) StorageEngine(storageEngine interface{}) IndexOptionsBuilder { iob.document = append(iob.document, bson.E{"storageEngine", storageEngine}) return iob } // Unique specifies a value for the unique option. // // Deprecated: Use the IndexOptions.SetUnique function in mongo/options instead. func (iob IndexOptionsBuilder) Unique(unique bool) IndexOptionsBuilder { iob.document = append(iob.document, bson.E{"unique", unique}) return iob } // Version specifies a value for the version option. // // Deprecated: Use the IndexOptions.SetVersion function in mongo/options instead. func (iob IndexOptionsBuilder) Version(version int32) IndexOptionsBuilder { iob.document = append(iob.document, bson.E{"v", version}) return iob } // DefaultLanguage specifies a value for the default_language option. // // Deprecated: Use the IndexOptions.SetDefaultLanguage function in mongo/options instead. func (iob IndexOptionsBuilder) DefaultLanguage(defaultLanguage string) IndexOptionsBuilder { iob.document = append(iob.document, bson.E{"default_language", defaultLanguage}) return iob } // LanguageOverride specifies a value for the language_override option. // // Deprecated: Use the IndexOptions.SetLanguageOverride function in mongo/options instead. func (iob IndexOptionsBuilder) LanguageOverride(languageOverride string) IndexOptionsBuilder { iob.document = append(iob.document, bson.E{"language_override", languageOverride}) return iob } // TextVersion specifies a value for the textIndexVersion option. // // Deprecated: Use the IndexOptions.SetTextVersion function in mongo/options instead. func (iob IndexOptionsBuilder) TextVersion(textVersion int32) IndexOptionsBuilder { iob.document = append(iob.document, bson.E{"textIndexVersion", textVersion}) return iob } // Weights specifies a value for the weights option. // // Deprecated: Use the IndexOptions.SetWeights function in mongo/options instead. func (iob IndexOptionsBuilder) Weights(weights interface{}) IndexOptionsBuilder { iob.document = append(iob.document, bson.E{"weights", weights}) return iob } // SphereVersion specifies a value for the 2dsphereIndexVersion option. // // Deprecated: Use the IndexOptions.SetSphereVersion function in mongo/options instead. func (iob IndexOptionsBuilder) SphereVersion(sphereVersion int32) IndexOptionsBuilder { iob.document = append(iob.document, bson.E{"2dsphereIndexVersion", sphereVersion}) return iob } // Bits specifies a value for the bits option. // // Deprecated: Use the IndexOptions.SetBits function in mongo/options instead. func (iob IndexOptionsBuilder) Bits(bits int32) IndexOptionsBuilder { iob.document = append(iob.document, bson.E{"bits", bits}) return iob } // Max specifies a value for the max option. // // Deprecated: Use the IndexOptions.SetMax function in mongo/options instead. func (iob IndexOptionsBuilder) Max(max float64) IndexOptionsBuilder { iob.document = append(iob.document, bson.E{"max", max}) return iob } // Min specifies a value for the min option. // // Deprecated: Use the IndexOptions.SetMin function in mongo/options instead. func (iob IndexOptionsBuilder) Min(min float64) IndexOptionsBuilder { iob.document = append(iob.document, bson.E{"min", min}) return iob } // BucketSize specifies a value for the bucketSize option. // // Deprecated: Use the IndexOptions.SetBucketSize function in mongo/options instead. func (iob IndexOptionsBuilder) BucketSize(bucketSize int32) IndexOptionsBuilder { iob.document = append(iob.document, bson.E{"bucketSize", bucketSize}) return iob } // PartialFilterExpression specifies a value for the partialFilterExpression option. // // Deprecated: Use the IndexOptions.SetPartialFilterExpression function in mongo/options instead. func (iob IndexOptionsBuilder) PartialFilterExpression(partialFilterExpression interface{}) IndexOptionsBuilder { iob.document = append(iob.document, bson.E{"partialFilterExpression", partialFilterExpression}) return iob } // Collation specifies a value for the collation option. // // Deprecated: Use the IndexOptions.SetCollation function in mongo/options instead. func (iob IndexOptionsBuilder) Collation(collation interface{}) IndexOptionsBuilder { iob.document = append(iob.document, bson.E{"collation", collation}) return iob } // Build finishes constructing an the builder. // // Deprecated: Use the IndexOptions type in the mongo/options package instead. func (iob IndexOptionsBuilder) Build() bson.D { return iob.document }	6.53 KB	2025-05-25 12:27
📄 index_view.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "bytes" "context" "errors" "fmt" "strconv" "go.mongodb.org/mongo-driver/bson" "go.mongodb.org/mongo-driver/bson/bsontype" "go.mongodb.org/mongo-driver/mongo/description" "go.mongodb.org/mongo-driver/mongo/options" "go.mongodb.org/mongo-driver/mongo/readpref" "go.mongodb.org/mongo-driver/mongo/writeconcern" "go.mongodb.org/mongo-driver/x/bsonx/bsoncore" "go.mongodb.org/mongo-driver/x/mongo/driver" "go.mongodb.org/mongo-driver/x/mongo/driver/operation" "go.mongodb.org/mongo-driver/x/mongo/driver/session" ) // ErrInvalidIndexValue is returned if an index is created with a keys document that has a value that is not a number // or string. var ErrInvalidIndexValue = errors.New("invalid index value") // ErrNonStringIndexName is returned if an index is created with a name that is not a string. var ErrNonStringIndexName = errors.New("index name must be a string") // ErrMultipleIndexDrop is returned if multiple indexes would be dropped from a call to IndexView.DropOne. var ErrMultipleIndexDrop = errors.New("multiple indexes would be dropped") // 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(). type IndexView struct { coll Collection } // IndexModel represents a new index to be created. 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.IndexOptions } func isNamespaceNotFoundError(err error) bool { if de, ok := err.(driver.Error); ok { return de.Code == 26 } return false } // 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/. func (iv IndexView) List(ctx context.Context, opts ...options.ListIndexesOptions) (Cursor, error) { if ctx == nil { ctx = context.Background() } sess := sessionFromContext(ctx) if sess == nil && iv.coll.client.sessionPool != nil { sess = session.NewImplicitClientSession(iv.coll.client.sessionPool, iv.coll.client.id) } err := iv.coll.client.validSession(sess) if err != nil { closeImplicitSession(sess) return nil, err } selector := description.CompositeSelector([]description.ServerSelector{ description.ReadPrefSelector(readpref.Primary()), description.LatencySelector(iv.coll.client.localThreshold), }) selector = makeReadPrefSelector(sess, selector, iv.coll.client.localThreshold) // TODO(GODRIVER-3038): This operation should pass CSE to the ListIndexes // Crypt setter to be applied to the operation. op := operation.NewListIndexes(). Session(sess).CommandMonitor(iv.coll.client.monitor). ServerSelector(selector).ClusterClock(iv.coll.client.clock). Database(iv.coll.db.name).Collection(iv.coll.name). Deployment(iv.coll.client.deployment).ServerAPI(iv.coll.client.serverAPI). Timeout(iv.coll.client.timeout) cursorOpts := iv.coll.client.createBaseCursorOptions() cursorOpts.MarshalValueEncoderFn = newEncoderFn(iv.coll.bsonOpts, iv.coll.registry) lio := options.MergeListIndexesOptions(opts...) if lio.BatchSize != nil { op = op.BatchSize(lio.BatchSize) cursorOpts.BatchSize = lio.BatchSize } op = op.MaxTime(lio.MaxTime) retry := driver.RetryNone if iv.coll.client.retryReads { retry = driver.RetryOncePerCommand } op.Retry(retry) err = op.Execute(ctx) if err != nil { // for namespaceNotFound errors, return an empty cursor and do not throw an error closeImplicitSession(sess) if isNamespaceNotFoundError(err) { return newEmptyCursor(), nil } return nil, replaceErrors(err) } bc, err := op.Result(cursorOpts) if err != nil { closeImplicitSession(sess) return nil, replaceErrors(err) } cursor, err := newCursorWithSession(bc, iv.coll.bsonOpts, iv.coll.registry, sess) return cursor, replaceErrors(err) } // ListSpecifications executes a List command and returns a slice of returned IndexSpecifications func (iv IndexView) ListSpecifications(ctx context.Context, opts ...options.ListIndexesOptions) ([]IndexSpecification, error) { cursor, err := iv.List(ctx, opts...) if err != nil { return nil, err } var results []IndexSpecification err = cursor.All(ctx, &results) if err != nil { return nil, err } ns := iv.coll.db.Name() + "." + iv.coll.Name() for _, res := range results { // Pre-4.4 servers report a namespace in their responses, so we only set Namespace manually if it was not in // the response. res.Namespace = ns } return results, nil } // 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 (iv IndexView) CreateOne(ctx context.Context, model IndexModel, opts ...options.CreateIndexesOptions) (string, error) { names, err := iv.CreateMany(ctx, []IndexModel{model}, opts...) if err != nil { return "", err } return names[0], nil } // 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/. func (iv IndexView) CreateMany(ctx context.Context, models []IndexModel, opts ...options.CreateIndexesOptions) ([]string, error) { names := make([]string, 0, len(models)) var indexes bsoncore.Document aidx, indexes := bsoncore.AppendArrayStart(indexes) for i, model := range models { if model.Keys == nil { return nil, fmt.Errorf("index model keys cannot be nil") } if isUnorderedMap(model.Keys) { return nil, ErrMapForOrderedArgument{"keys"} } keys, err := marshal(model.Keys, iv.coll.bsonOpts, iv.coll.registry) if err != nil { return nil, err } name, err := getOrGenerateIndexName(keys, model) if err != nil { return nil, err } names = append(names, name) var iidx int32 iidx, indexes = bsoncore.AppendDocumentElementStart(indexes, strconv.Itoa(i)) indexes = bsoncore.AppendDocumentElement(indexes, "key", keys) if model.Options == nil { model.Options = options.Index() } model.Options.SetName(name) optsDoc, err := iv.createOptionsDoc(model.Options) if err != nil { return nil, err } indexes = bsoncore.AppendDocument(indexes, optsDoc) indexes, err = bsoncore.AppendDocumentEnd(indexes, iidx) if err != nil { return nil, err } } indexes, err := bsoncore.AppendArrayEnd(indexes, aidx) if err != nil { return nil, err } sess := sessionFromContext(ctx) if sess == nil && iv.coll.client.sessionPool != nil { sess = session.NewImplicitClientSession(iv.coll.client.sessionPool, iv.coll.client.id) defer sess.EndSession() } err = iv.coll.client.validSession(sess) if err != nil { return nil, err } wc := iv.coll.writeConcern if sess.TransactionRunning() { wc = nil } if !writeconcern.AckWrite(wc) { sess = nil } selector := makePinnedSelector(sess, iv.coll.writeSelector) option := options.MergeCreateIndexesOptions(opts...) // TODO(GODRIVER-3038): This operation should pass CSE to the CreateIndexes // Crypt setter to be applied to the operation. // // This was added in GODRIVER-2413 for the 2.0 major release. op := operation.NewCreateIndexes(indexes). Session(sess).WriteConcern(wc).ClusterClock(iv.coll.client.clock). Database(iv.coll.db.name).Collection(iv.coll.name).CommandMonitor(iv.coll.client.monitor). Deployment(iv.coll.client.deployment).ServerSelector(selector).ServerAPI(iv.coll.client.serverAPI). Timeout(iv.coll.client.timeout).MaxTime(option.MaxTime) if option.CommitQuorum != nil { commitQuorum, err := marshalValue(option.CommitQuorum, iv.coll.bsonOpts, iv.coll.registry) if err != nil { return nil, err } op.CommitQuorum(commitQuorum) } err = op.Execute(ctx) if err != nil { _, err = processWriteError(err) return nil, err } return names, nil } func (iv IndexView) createOptionsDoc(opts options.IndexOptions) (bsoncore.Document, error) { optsDoc := bsoncore.Document{} if opts.Background != nil { optsDoc = bsoncore.AppendBooleanElement(optsDoc, "background", opts.Background) } if opts.ExpireAfterSeconds != nil { optsDoc = bsoncore.AppendInt32Element(optsDoc, "expireAfterSeconds", opts.ExpireAfterSeconds) } if opts.Name != nil { optsDoc = bsoncore.AppendStringElement(optsDoc, "name", opts.Name) } if opts.Sparse != nil { optsDoc = bsoncore.AppendBooleanElement(optsDoc, "sparse", opts.Sparse) } if opts.StorageEngine != nil { doc, err := marshal(opts.StorageEngine, iv.coll.bsonOpts, iv.coll.registry) if err != nil { return nil, err } optsDoc = bsoncore.AppendDocumentElement(optsDoc, "storageEngine", doc) } if opts.Unique != nil { optsDoc = bsoncore.AppendBooleanElement(optsDoc, "unique", opts.Unique) } if opts.Version != nil { optsDoc = bsoncore.AppendInt32Element(optsDoc, "v", opts.Version) } if opts.DefaultLanguage != nil { optsDoc = bsoncore.AppendStringElement(optsDoc, "default_language", opts.DefaultLanguage) } if opts.LanguageOverride != nil { optsDoc = bsoncore.AppendStringElement(optsDoc, "language_override", opts.LanguageOverride) } if opts.TextVersion != nil { optsDoc = bsoncore.AppendInt32Element(optsDoc, "textIndexVersion", opts.TextVersion) } if opts.Weights != nil { doc, err := marshal(opts.Weights, iv.coll.bsonOpts, iv.coll.registry) if err != nil { return nil, err } optsDoc = bsoncore.AppendDocumentElement(optsDoc, "weights", doc) } if opts.SphereVersion != nil { optsDoc = bsoncore.AppendInt32Element(optsDoc, "2dsphereIndexVersion", opts.SphereVersion) } if opts.Bits != nil { optsDoc = bsoncore.AppendInt32Element(optsDoc, "bits", opts.Bits) } if opts.Max != nil { optsDoc = bsoncore.AppendDoubleElement(optsDoc, "max", opts.Max) } if opts.Min != nil { optsDoc = bsoncore.AppendDoubleElement(optsDoc, "min", opts.Min) } if opts.BucketSize != nil { optsDoc = bsoncore.AppendInt32Element(optsDoc, "bucketSize", opts.BucketSize) } if opts.PartialFilterExpression != nil { doc, err := marshal(opts.PartialFilterExpression, iv.coll.bsonOpts, iv.coll.registry) if err != nil { return nil, err } optsDoc = bsoncore.AppendDocumentElement(optsDoc, "partialFilterExpression", doc) } if opts.Collation != nil { optsDoc = bsoncore.AppendDocumentElement(optsDoc, "collation", bsoncore.Document(opts.Collation.ToDocument())) } if opts.WildcardProjection != nil { doc, err := marshal(opts.WildcardProjection, iv.coll.bsonOpts, iv.coll.registry) if err != nil { return nil, err } optsDoc = bsoncore.AppendDocumentElement(optsDoc, "wildcardProjection", doc) } if opts.Hidden != nil { optsDoc = bsoncore.AppendBooleanElement(optsDoc, "hidden", opts.Hidden) } return optsDoc, nil } func (iv IndexView) drop(ctx context.Context, name string, opts ...options.DropIndexesOptions) (bson.Raw, error) { if ctx == nil { ctx = context.Background() } sess := sessionFromContext(ctx) if sess == nil && iv.coll.client.sessionPool != nil { sess = session.NewImplicitClientSession(iv.coll.client.sessionPool, iv.coll.client.id) defer sess.EndSession() } err := iv.coll.client.validSession(sess) if err != nil { return nil, err } wc := iv.coll.writeConcern if sess.TransactionRunning() { wc = nil } if !writeconcern.AckWrite(wc) { sess = nil } selector := makePinnedSelector(sess, iv.coll.writeSelector) dio := options.MergeDropIndexesOptions(opts...) // TODO(GODRIVER-3038): This operation should pass CSE to the DropIndexes // Crypt setter to be applied to the operation. op := operation.NewDropIndexes(name). Session(sess).WriteConcern(wc).CommandMonitor(iv.coll.client.monitor). ServerSelector(selector).ClusterClock(iv.coll.client.clock). Database(iv.coll.db.name).Collection(iv.coll.name). Deployment(iv.coll.client.deployment).ServerAPI(iv.coll.client.serverAPI). Timeout(iv.coll.client.timeout).MaxTime(dio.MaxTime) err = op.Execute(ctx) if err != nil { return nil, replaceErrors(err) } // TODO: it's weird to return a bson.Raw here because we have to convert the result back to BSON ridx, res := bsoncore.AppendDocumentStart(nil) res = bsoncore.AppendInt32Element(res, "nIndexesWas", op.Result().NIndexesWas) res, _ = bsoncore.AppendDocumentEnd(res, ridx) return res, nil } // DropOne executes a dropIndexes operation to drop an index on the collection. If the operation succeeds, this returns // a BSON document in the form {nIndexesWas: <int32>}. The "nIndexesWas" field in the response contains the number of // indexes that existed prior to the drop. // // 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 (iv IndexView) DropOne(ctx context.Context, name string, opts ...options.DropIndexesOptions) (bson.Raw, error) { if name == "" { return nil, ErrMultipleIndexDrop } return iv.drop(ctx, name, opts...) } // DropAll executes a dropIndexes operation to drop all indexes on the collection. If the operation succeeds, this // returns a BSON document in the form {nIndexesWas: <int32>}. The "nIndexesWas" field in the response contains the // number of indexes that existed prior to the drop. // // 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 (iv IndexView) DropAll(ctx context.Context, opts ...options.DropIndexesOptions) (bson.Raw, error) { return iv.drop(ctx, "", opts...) } func getOrGenerateIndexName(keySpecDocument bsoncore.Document, model IndexModel) (string, error) { if model.Options != nil && model.Options.Name != nil { return model.Options.Name, nil } name := bytes.NewBufferString("") first := true elems, err := keySpecDocument.Elements() if err != nil { return "", err } for _, elem := range elems { if !first { _, err := name.WriteRune('_') if err != nil { return "", err } } _, err := name.WriteString(elem.Key()) if err != nil { return "", err } _, err = name.WriteRune('_') if err != nil { return "", err } var value string bsonValue := elem.Value() switch bsonValue.Type { case bsontype.Int32: value = fmt.Sprintf("%d", bsonValue.Int32()) case bsontype.Int64: value = fmt.Sprintf("%d", bsonValue.Int64()) case bsontype.String: value = bsonValue.StringValue() default: return "", ErrInvalidIndexValue } _, err = name.WriteString(value) if err != nil { return "", err } first = false } return name.String(), nil }	15.77 KB	2025-05-25 12:27
📁 integration	-	2025-05-25 12:27
📄 mongo.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo // import "go.mongodb.org/mongo-driver/mongo" import ( "bytes" "context" "errors" "fmt" "io" "net" "reflect" "strconv" "strings" "go.mongodb.org/mongo-driver/internal/codecutil" "go.mongodb.org/mongo-driver/mongo/options" "go.mongodb.org/mongo-driver/x/bsonx/bsoncore" "go.mongodb.org/mongo-driver/bson" "go.mongodb.org/mongo-driver/bson/bsoncodec" "go.mongodb.org/mongo-driver/bson/bsonrw" "go.mongodb.org/mongo-driver/bson/bsontype" "go.mongodb.org/mongo-driver/bson/primitive" ) // Dialer is used to make network connections. type Dialer interface { DialContext(ctx context.Context, network, address string) (net.Conn, error) } // BSONAppender is an interface implemented by types that can marshal a // provided type into BSON bytes and append those bytes to the provided []byte. // The AppendBSON can return a non-nil error and non-nil []byte. The AppendBSON // method may also write incomplete BSON to the []byte. // // Deprecated: BSONAppender is unused and will be removed in Go Driver 2.0. type BSONAppender interface { AppendBSON([]byte, interface{}) ([]byte, error) } // BSONAppenderFunc is an adapter function that allows any function that // satisfies the AppendBSON method signature to be used where a BSONAppender is // used. // // Deprecated: BSONAppenderFunc is unused and will be removed in Go Driver 2.0. type BSONAppenderFunc func([]byte, interface{}) ([]byte, error) // AppendBSON implements the BSONAppender interface // // Deprecated: BSONAppenderFunc is unused and will be removed in Go Driver 2.0. func (baf BSONAppenderFunc) AppendBSON(dst []byte, val interface{}) ([]byte, error) { return baf(dst, val) } // MarshalError is returned when attempting to marshal a value into a document // results in an error. type MarshalError struct { Value interface{} Err error } // Error implements the error interface. func (me MarshalError) Error() string { return fmt.Sprintf("cannot marshal type %s to a BSON Document: %v", reflect.TypeOf(me.Value), me.Err) } // 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", 1010001000}}}}}}, // } type Pipeline []bson.D // bvwPool is a pool of BSON value writers. BSON value writers var bvwPool = bsonrw.NewBSONValueWriterPool() // getEncoder takes a writer, BSON options, and a BSON registry and returns a properly configured // bson.Encoder that writes to the given writer. func getEncoder( w io.Writer, opts options.BSONOptions, reg bsoncodec.Registry, ) (bson.Encoder, error) { vw := bvwPool.Get(w) enc, err := bson.NewEncoder(vw) if err != nil { return nil, err } if opts != nil { if opts.ErrorOnInlineDuplicates { enc.ErrorOnInlineDuplicates() } if opts.IntMinSize { enc.IntMinSize() } if opts.NilByteSliceAsEmpty { enc.NilByteSliceAsEmpty() } if opts.NilMapAsEmpty { enc.NilMapAsEmpty() } if opts.NilSliceAsEmpty { enc.NilSliceAsEmpty() } if opts.OmitZeroStruct { enc.OmitZeroStruct() } if opts.StringifyMapKeysWithFmt { enc.StringifyMapKeysWithFmt() } if opts.UseJSONStructTags { enc.UseJSONStructTags() } } if reg != nil { // TODO:(GODRIVER-2719): Remove error handling. if err := enc.SetRegistry(reg); err != nil { return nil, err } } return enc, nil } // newEncoderFn will return a function for constructing an encoder based on the // provided codec options. func newEncoderFn(opts options.BSONOptions, registry bsoncodec.Registry) codecutil.EncoderFn { return func(w io.Writer) (bson.Encoder, error) { return getEncoder(w, opts, registry) } } // marshal marshals the given value as a BSON document. Byte slices are always converted to a // bson.Raw before marshaling. // // If bsonOpts and registry are specified, the encoder is configured with the requested behaviors. // If they are nil, the default behaviors are used. func marshal( val interface{}, bsonOpts options.BSONOptions, registry bsoncodec.Registry, ) (bsoncore.Document, error) { if registry == nil { registry = bson.DefaultRegistry } if val == nil { return nil, ErrNilDocument } if bs, ok := val.([]byte); ok { // Slight optimization so we'll just use MarshalBSON and not go through the codec machinery. val = bson.Raw(bs) } buf := new(bytes.Buffer) enc, err := getEncoder(buf, bsonOpts, registry) if err != nil { return nil, fmt.Errorf("error configuring BSON encoder: %w", err) } err = enc.Encode(val) if err != nil { return nil, MarshalError{Value: val, Err: err} } return buf.Bytes(), nil } // ensureID inserts the given ObjectID as an element named "_id" at the // beginning of the given BSON document if there is not an "_id" already. // If the given ObjectID is primitive.NilObjectID, a new object ID will be // generated with time.Now(). // // If there is already an element named "_id", the document is not modified. It // returns the resulting document and the decoded Go value of the "_id" element. func ensureID( doc bsoncore.Document, oid primitive.ObjectID, bsonOpts options.BSONOptions, reg bsoncodec.Registry, ) (bsoncore.Document, interface{}, error) { if reg == nil { reg = bson.DefaultRegistry } // Try to find the "_id" element. If it exists, try to unmarshal just the // "_id" field as an interface{} and return it along with the unmodified // BSON document. if _, err := doc.LookupErr("_id"); err == nil { var id struct { ID interface{} `bson:"_id"` } dec, err := getDecoder(doc, bsonOpts, reg) if err != nil { return nil, nil, fmt.Errorf("error configuring BSON decoder: %w", err) } err = dec.Decode(&id) if err != nil { return nil, nil, fmt.Errorf("error unmarshaling BSON document: %w", err) } return doc, id.ID, nil } // We couldn't find an "_id" element, so add one with the value of the // provided ObjectID. olddoc := doc // Reserve an extra 17 bytes for the "_id" field we're about to add: // type (1) + "_id" (3) + terminator (1) + object ID (12) const extraSpace = 17 doc = make(bsoncore.Document, 0, len(olddoc)+extraSpace) _, doc = bsoncore.ReserveLength(doc) if oid.IsZero() { oid = primitive.NewObjectID() } doc = bsoncore.AppendObjectIDElement(doc, "_id", oid) // Remove and re-write the BSON document length header. const int32Len = 4 doc = append(doc, olddoc[int32Len:]...) doc = bsoncore.UpdateLength(doc, 0, int32(len(doc))) return doc, oid, nil } func ensureDollarKey(doc bsoncore.Document) error { firstElem, err := doc.IndexErr(0) if err != nil { return errors.New("update document must have at least one element") } if !strings.HasPrefix(firstElem.Key(), "$") { return errors.New("update document must contain key beginning with '$'") } return nil } func ensureNoDollarKey(doc bsoncore.Document) error { if elem, err := doc.IndexErr(0); err == nil && strings.HasPrefix(elem.Key(), "$") { return errors.New("replacement document cannot contain keys beginning with '$'") } return nil } func marshalAggregatePipeline( pipeline interface{}, bsonOpts options.BSONOptions, registry bsoncodec.Registry, ) (bsoncore.Document, bool, error) { switch t := pipeline.(type) { case bsoncodec.ValueMarshaler: btype, val, err := t.MarshalBSONValue() if err != nil { return nil, false, err } if btype != bsontype.Array { return nil, false, fmt.Errorf("ValueMarshaler returned a %v, but was expecting %v", btype, bsontype.Array) } var hasOutputStage bool pipelineDoc := bsoncore.Document(val) values, _ := pipelineDoc.Values() if pipelineLen := len(values); pipelineLen > 0 { if finalDoc, ok := values[pipelineLen-1].DocumentOK(); ok { if elem, err := finalDoc.IndexErr(0); err == nil && (elem.Key() == "$out" \|\| elem.Key() == "$merge") { hasOutputStage = true } } } return pipelineDoc, hasOutputStage, nil default: val := reflect.ValueOf(t) if !val.IsValid() \|\| (val.Kind() != reflect.Slice && val.Kind() != reflect.Array) { return nil, false, fmt.Errorf("can only marshal slices and arrays into aggregation pipelines, but got %v", val.Kind()) } var hasOutputStage bool valLen := val.Len() switch t := pipeline.(type) { // Explicitly forbid non-empty pipelines that are semantically single documents // and are implemented as slices. case bson.D, bson.Raw, bsoncore.Document: if valLen > 0 { return nil, false, fmt.Errorf("%T is not an allowed pipeline type as it represents a single document. Use bson.A or mongo.Pipeline instead", t) } // bsoncore.Arrays do not need to be marshaled. Only check validity and presence of output stage. case bsoncore.Array: if err := t.Validate(); err != nil { return nil, false, err } values, err := t.Values() if err != nil { return nil, false, err } numVals := len(values) if numVals == 0 { return bsoncore.Document(t), false, nil } // If not empty, check if first value of the last stage is $out or $merge. if lastStage, ok := values[numVals-1].DocumentOK(); ok { if elem, err := lastStage.IndexErr(0); err == nil && (elem.Key() == "$out" \|\| elem.Key() == "$merge") { hasOutputStage = true } } return bsoncore.Document(t), hasOutputStage, nil } aidx, arr := bsoncore.AppendArrayStart(nil) for idx := 0; idx < valLen; idx++ { doc, err := marshal(val.Index(idx).Interface(), bsonOpts, registry) if err != nil { return nil, false, err } if idx == valLen-1 { if elem, err := doc.IndexErr(0); err == nil && (elem.Key() == "$out" \|\| elem.Key() == "$merge") { hasOutputStage = true } } arr = bsoncore.AppendDocumentElement(arr, strconv.Itoa(idx), doc) } arr, _ = bsoncore.AppendArrayEnd(arr, aidx) return arr, hasOutputStage, nil } } func marshalUpdateValue( update interface{}, bsonOpts options.BSONOptions, registry bsoncodec.Registry, dollarKeysAllowed bool, ) (bsoncore.Value, error) { documentCheckerFunc := ensureDollarKey if !dollarKeysAllowed { documentCheckerFunc = ensureNoDollarKey } var u bsoncore.Value var err error switch t := update.(type) { case nil: return u, ErrNilDocument case primitive.D: u.Type = bsontype.EmbeddedDocument u.Data, err = marshal(update, bsonOpts, registry) if err != nil { return u, err } return u, documentCheckerFunc(u.Data) case bson.Raw: u.Type = bsontype.EmbeddedDocument u.Data = t return u, documentCheckerFunc(u.Data) case bsoncore.Document: u.Type = bsontype.EmbeddedDocument u.Data = t return u, documentCheckerFunc(u.Data) case []byte: u.Type = bsontype.EmbeddedDocument u.Data = t return u, documentCheckerFunc(u.Data) case bsoncodec.Marshaler: u.Type = bsontype.EmbeddedDocument u.Data, err = t.MarshalBSON() if err != nil { return u, err } return u, documentCheckerFunc(u.Data) case bsoncodec.ValueMarshaler: u.Type, u.Data, err = t.MarshalBSONValue() if err != nil { return u, err } if u.Type != bsontype.Array && u.Type != bsontype.EmbeddedDocument { return u, fmt.Errorf("ValueMarshaler returned a %v, but was expecting %v or %v", u.Type, bsontype.Array, bsontype.EmbeddedDocument) } return u, err default: val := reflect.ValueOf(t) if !val.IsValid() { return u, fmt.Errorf("can only marshal slices and arrays into update pipelines, but got %v", val.Kind()) } if val.Kind() != reflect.Slice && val.Kind() != reflect.Array { u.Type = bsontype.EmbeddedDocument u.Data, err = marshal(update, bsonOpts, registry) if err != nil { return u, err } return u, documentCheckerFunc(u.Data) } u.Type = bsontype.Array aidx, arr := bsoncore.AppendArrayStart(nil) valLen := val.Len() for idx := 0; idx < valLen; idx++ { doc, err := marshal(val.Index(idx).Interface(), bsonOpts, registry) if err != nil { return u, err } if err := documentCheckerFunc(doc); err != nil { return u, err } arr = bsoncore.AppendDocumentElement(arr, strconv.Itoa(idx), doc) } u.Data, _ = bsoncore.AppendArrayEnd(arr, aidx) return u, err } } func marshalValue( val interface{}, bsonOpts options.BSONOptions, registry bsoncodec.Registry, ) (bsoncore.Value, error) { return codecutil.MarshalValue(val, newEncoderFn(bsonOpts, registry)) } // Build the aggregation pipeline for the CountDocument command. func countDocumentsAggregatePipeline( filter interface{}, encOpts options.BSONOptions, registry bsoncodec.Registry, opts options.CountOptions, ) (bsoncore.Document, error) { filterDoc, err := marshal(filter, encOpts, registry) if err != nil { return nil, err } aidx, arr := bsoncore.AppendArrayStart(nil) didx, arr := bsoncore.AppendDocumentElementStart(arr, strconv.Itoa(0)) arr = bsoncore.AppendDocumentElement(arr, "$match", filterDoc) arr, _ = bsoncore.AppendDocumentEnd(arr, didx) index := 1 if opts != nil { if opts.Skip != nil { didx, arr = bsoncore.AppendDocumentElementStart(arr, strconv.Itoa(index)) arr = bsoncore.AppendInt64Element(arr, "$skip", opts.Skip) arr, _ = bsoncore.AppendDocumentEnd(arr, didx) index++ } if opts.Limit != nil { didx, arr = bsoncore.AppendDocumentElementStart(arr, strconv.Itoa(index)) arr = bsoncore.AppendInt64Element(arr, "$limit", *opts.Limit) arr, _ = bsoncore.AppendDocumentEnd(arr, didx) index++ } } didx, arr = bsoncore.AppendDocumentElementStart(arr, strconv.Itoa(index)) iidx, arr := bsoncore.AppendDocumentElementStart(arr, "$group") arr = bsoncore.AppendInt32Element(arr, "_id", 1) iiidx, arr := bsoncore.AppendDocumentElementStart(arr, "n") arr = bsoncore.AppendInt32Element(arr, "$sum", 1) arr, _ = bsoncore.AppendDocumentEnd(arr, iiidx) arr, _ = bsoncore.AppendDocumentEnd(arr, iidx) arr, _ = bsoncore.AppendDocumentEnd(arr, didx) return bsoncore.AppendArrayEnd(arr, aidx) }	13.95 KB	2025-05-25 12:27
📄 mongo_test.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "errors" "fmt" "testing" "go.mongodb.org/mongo-driver/bson" "go.mongodb.org/mongo-driver/bson/bsoncodec" "go.mongodb.org/mongo-driver/bson/bsontype" "go.mongodb.org/mongo-driver/bson/primitive" "go.mongodb.org/mongo-driver/internal/assert" "go.mongodb.org/mongo-driver/internal/codecutil" "go.mongodb.org/mongo-driver/internal/require" "go.mongodb.org/mongo-driver/mongo/options" "go.mongodb.org/mongo-driver/x/bsonx/bsoncore" ) func TestEnsureID(t testing.T) { t.Parallel() oid := primitive.NewObjectID() testCases := []struct { description string // TODO: Registry? DecodeOptions? doc bsoncore.Document oid primitive.ObjectID want bsoncore.Document wantID interface{} }{ { description: "missing _id should be first element", doc: bsoncore.NewDocumentBuilder(). AppendString("foo", "bar"). AppendString("baz", "quix"). AppendString("hello", "world"). Build(), want: bsoncore.NewDocumentBuilder(). AppendObjectID("_id", oid). AppendString("foo", "bar"). AppendString("baz", "quix"). AppendString("hello", "world"). Build(), wantID: oid, }, { description: "existing ObjectID _id as should remain in place", doc: bsoncore.NewDocumentBuilder(). AppendString("foo", "bar"). AppendObjectID("_id", oid). AppendString("baz", "quix"). AppendString("hello", "world"). Build(), want: bsoncore.NewDocumentBuilder(). AppendString("foo", "bar"). AppendObjectID("_id", oid). AppendString("baz", "quix"). AppendString("hello", "world"). Build(), wantID: oid, }, { description: "existing float _id as should remain in place", doc: bsoncore.NewDocumentBuilder(). AppendString("foo", "bar"). AppendDouble("_id", 3.14159). AppendString("baz", "quix"). AppendString("hello", "world"). Build(), want: bsoncore.NewDocumentBuilder(). AppendString("foo", "bar"). AppendDouble("_id", 3.14159). AppendString("baz", "quix"). AppendString("hello", "world"). Build(), wantID: 3.14159, }, { description: "existing float _id as first element should remain first element", doc: bsoncore.NewDocumentBuilder(). AppendDouble("_id", 3.14159). AppendString("foo", "bar"). AppendString("baz", "quix"). AppendString("hello", "world"). Build(), want: bsoncore.NewDocumentBuilder(). AppendDouble("_id", 3.14159). AppendString("foo", "bar"). AppendString("baz", "quix"). AppendString("hello", "world"). Build(), wantID: 3.14159, }, { description: "existing binary _id as first field should not be overwritten", doc: bsoncore.NewDocumentBuilder(). AppendBinary("bin", 0, []byte{0, 0, 0}). AppendString("_id", "LongEnoughIdentifier"). Build(), want: bsoncore.NewDocumentBuilder(). AppendBinary("bin", 0, []byte{0, 0, 0}). AppendString("_id", "LongEnoughIdentifier"). Build(), wantID: "LongEnoughIdentifier", }, } for _, tc := range testCases { tc := tc // Capture range variable. t.Run(tc.description, func(t testing.T) { t.Parallel() got, gotID, err := ensureID(tc.doc, oid, nil, nil) require.NoError(t, err, "ensureID error") assert.Equal(t, tc.want, got, "expected and actual documents are different") assert.Equal(t, tc.wantID, gotID, "expected and actual IDs are different") // Ensure that if the unmarshaled "_id" value is a // primitive.ObjectID that it is a deep copy and does not share any // memory with the document byte slice. if oid, ok := gotID.(primitive.ObjectID); ok { assert.DifferentAddressRanges(t, tc.doc, oid[:]) } }) } } func TestEnsureID_NilObjectID(t testing.T) { t.Parallel() doc := bsoncore.NewDocumentBuilder(). AppendString("foo", "bar"). Build() got, gotIDI, err := ensureID(doc, primitive.NilObjectID, nil, nil) assert.NoError(t, err) gotID, ok := gotIDI.(primitive.ObjectID) assert.True(t, ok) assert.NotEqual(t, primitive.NilObjectID, gotID) want := bsoncore.NewDocumentBuilder(). AppendObjectID("_id", gotID). AppendString("foo", "bar"). Build() assert.Equal(t, want, got) } func TestMarshalAggregatePipeline(t testing.T) { // []byte of [{{"$limit", 12345}}] index, arr := bsoncore.AppendArrayStart(nil) dindex, arr := bsoncore.AppendDocumentElementStart(arr, "0") arr = bsoncore.AppendInt32Element(arr, "$limit", 12345) arr, _ = bsoncore.AppendDocumentEnd(arr, dindex) arr, _ = bsoncore.AppendArrayEnd(arr, index) // []byte of {{"x", 1}} index, doc := bsoncore.AppendDocumentStart(nil) doc = bsoncore.AppendInt32Element(doc, "x", 1) doc, _ = bsoncore.AppendDocumentEnd(doc, index) // bsoncore.Array of [{{"$merge", {}}}] mergeStage := bsoncore.NewDocumentBuilder(). StartDocument("$merge"). FinishDocument(). Build() arrMergeStage := bsoncore.NewArrayBuilder().AppendDocument(mergeStage).Build() fooStage := bsoncore.NewDocumentBuilder().AppendString("foo", "bar").Build() bazStage := bsoncore.NewDocumentBuilder().AppendString("baz", "qux").Build() outStage := bsoncore.NewDocumentBuilder().AppendString("$out", "myColl").Build() // bsoncore.Array of [{{"foo", "bar"}}, {{"baz", "qux"}}, {{"$out", "myColl"}}] arrOutStage := bsoncore.NewArrayBuilder(). AppendDocument(fooStage). AppendDocument(bazStage). AppendDocument(outStage). Build() // bsoncore.Array of [{{"foo", "bar"}}, {{"$out", "myColl"}}, {{"baz", "qux"}}] arrMiddleOutStage := bsoncore.NewArrayBuilder(). AppendDocument(fooStage). AppendDocument(outStage). AppendDocument(bazStage). Build() testCases := []struct { name string pipeline interface{} arr bson.A hasOutputStage bool err error }{ { "Pipeline/error", Pipeline{{{"hello", func() {}}}}, nil, false, MarshalError{Value: primitive.D{}, Err: errors.New("no encoder found for func()")}, }, { "Pipeline/success", Pipeline{{{"hello", "world"}}, {{"pi", 3.14159}}}, bson.A{ bson.D{{"hello", "world"}}, bson.D{{"pi", 3.14159}}, }, false, nil, }, { "bson.A", bson.A{ bson.D{{"$limit", 12345}}, }, bson.A{ bson.D{{"$limit", 12345}}, }, false, nil, }, { "[]bson.D", []bson.D{{{"$limit", 12345}}}, bson.A{ bson.D{{"$limit", 12345}}, }, false, nil, }, { "primitive.A/error", primitive.A{"5"}, nil, false, MarshalError{Value: "", Err: errors.New("WriteString can only write while positioned on a Element or Value but is positioned on a TopLevel")}, }, { "primitive.A/success", primitive.A{bson.D{{"$limit", int32(12345)}}, map[string]interface{}{"$count": "foobar"}}, bson.A{ bson.D{{"$limit", int(12345)}}, bson.D{{"$count", "foobar"}}, }, false, nil, }, { "bson.A/error", bson.A{"5"}, nil, false, MarshalError{Value: "", Err: errors.New("WriteString can only write while positioned on a Element or Value but is positioned on a TopLevel")}, }, { "bson.A/success", bson.A{bson.D{{"$limit", int32(12345)}}, map[string]interface{}{"$count": "foobar"}}, bson.A{ bson.D{{"$limit", int32(12345)}}, bson.D{{"$count", "foobar"}}, }, false, nil, }, { "[]interface{}/error", []interface{}{"5"}, nil, false, MarshalError{Value: "", Err: errors.New("WriteString can only write while positioned on a Element or Value but is positioned on a TopLevel")}, }, { "[]interface{}/success", []interface{}{bson.D{{"$limit", int32(12345)}}, map[string]interface{}{"$count": "foobar"}}, bson.A{ bson.D{{"$limit", int32(12345)}}, bson.D{{"$count", "foobar"}}, }, false, nil, }, { "bsoncodec.ValueMarshaler/MarshalBSONValue error", bvMarsh{err: errors.New("MarshalBSONValue error")}, nil, false, errors.New("MarshalBSONValue error"), }, { "bsoncodec.ValueMarshaler/not array", bvMarsh{t: bsontype.String}, nil, false, fmt.Errorf("ValueMarshaler returned a %v, but was expecting %v", bsontype.String, bsontype.Array), }, { "bsoncodec.ValueMarshaler/UnmarshalBSONValue error", bvMarsh{err: errors.New("UnmarshalBSONValue error")}, nil, false, errors.New("UnmarshalBSONValue error"), }, { "bsoncodec.ValueMarshaler/success", bvMarsh{t: bsontype.Array, data: arr}, bson.A{ bson.D{{"$limit", int32(12345)}}, }, false, nil, }, { "bsoncodec.ValueMarshaler/success nil", bvMarsh{t: bsontype.Array}, nil, false, nil, }, { "nil", nil, nil, false, errors.New("can only marshal slices and arrays into aggregation pipelines, but got invalid"), }, { "not array or slice", int64(42), nil, false, errors.New("can only marshal slices and arrays into aggregation pipelines, but got int64"), }, { "array/error", [1]interface{}{int64(42)}, nil, false, MarshalError{Value: int64(0), Err: errors.New("WriteInt64 can only write while positioned on a Element or Value but is positioned on a TopLevel")}, }, { "array/success", [1]interface{}{primitive.D{{"$limit", int64(12345)}}}, bson.A{ bson.D{{"$limit", int64(12345)}}, }, false, nil, }, { "slice/error", []interface{}{int64(42)}, nil, false, MarshalError{Value: int64(0), Err: errors.New("WriteInt64 can only write while positioned on a Element or Value but is positioned on a TopLevel")}, }, { "slice/success", []interface{}{primitive.D{{"$limit", int64(12345)}}}, bson.A{ bson.D{{"$limit", int64(12345)}}, }, false, nil, }, { "hasOutputStage/out", bson.A{ bson.D{{"$out", bson.D{ {"db", "output-db"}, {"coll", "output-collection"}, }}}, }, bson.A{ bson.D{{"$out", bson.D{ {"db", "output-db"}, {"coll", "output-collection"}, }}}, }, true, nil, }, { "hasOutputStage/merge", bson.A{ bson.D{{"$merge", bson.D{ {"into", bson.D{ {"db", "output-db"}, {"coll", "output-collection"}, }}, }}}, }, bson.A{ bson.D{{"$merge", bson.D{ {"into", bson.D{ {"db", "output-db"}, {"coll", "output-collection"}, }}, }}}, }, true, nil, }, { "semantic single document/bson.D", bson.D{{"x", 1}}, nil, false, errors.New("primitive.D is not an allowed pipeline type as it represents a single document. Use bson.A or mongo.Pipeline instead"), }, { "semantic single document/bson.Raw", bson.Raw(doc), nil, false, errors.New("bson.Raw is not an allowed pipeline type as it represents a single document. Use bson.A or mongo.Pipeline instead"), }, { "semantic single document/bsoncore.Document", bsoncore.Document(doc), nil, false, errors.New("bsoncore.Document is not an allowed pipeline type as it represents a single document. Use bson.A or mongo.Pipeline instead"), }, { "semantic single document/empty bson.D", bson.D{}, bson.A{}, false, nil, }, { "semantic single document/empty bson.Raw", bson.Raw{}, bson.A{}, false, nil, }, { "semantic single document/empty bsoncore.Document", bsoncore.Document{}, bson.A{}, false, nil, }, { "bsoncore.Array/success", bsoncore.Array(arr), bson.A{ bson.D{{"$limit", int32(12345)}}, }, false, nil, }, { "bsoncore.Array/mergeStage", arrMergeStage, bson.A{ bson.D{{"$merge", bson.D{}}}, }, true, nil, }, { "bsoncore.Array/outStage", arrOutStage, bson.A{ bson.D{{"foo", "bar"}}, bson.D{{"baz", "qux"}}, bson.D{{"$out", "myColl"}}, }, true, nil, }, { "bsoncore.Array/middleOutStage", arrMiddleOutStage, bson.A{ bson.D{{"foo", "bar"}}, bson.D{{"$out", "myColl"}}, bson.D{{"baz", "qux"}}, }, false, nil, }, } for _, tc := range testCases { t.Run(tc.name, func(t testing.T) { arr, hasOutputStage, err := marshalAggregatePipeline(tc.pipeline, nil, nil) assert.Equal(t, tc.hasOutputStage, hasOutputStage, "expected hasOutputStage %v, got %v", tc.hasOutputStage, hasOutputStage) if tc.err != nil { assert.NotNil(t, err) assert.EqualError(t, err, tc.err.Error()) } else { assert.Nil(t, err) } var expected bsoncore.Document if tc.arr != nil { _, expectedBSON, err := bson.MarshalValue(tc.arr) assert.Nil(t, err, "MarshalValue error: %v", err) expected = bsoncore.Document(expectedBSON) } assert.Equal(t, expected, arr, "expected array %v, got %v", expected, arr) }) } } func TestMarshalValue(t testing.T) { t.Parallel() valueMarshaler := bvMarsh{ t: bson.TypeString, data: bsoncore.AppendString(nil, "foo"), } testCases := []struct { name string value interface{} bsonOpts options.BSONOptions registry bsoncodec.Registry want bsoncore.Value wantErr error }{ { name: "nil document", value: nil, wantErr: codecutil.ErrNilValue, }, { name: "value marshaler", value: valueMarshaler, want: bsoncore.Value{ Type: valueMarshaler.t, Data: valueMarshaler.data, }, }, { name: "document", value: bson.D{{Key: "x", Value: int64(1)}}, want: bsoncore.Value{ Type: bson.TypeEmbeddedDocument, Data: bsoncore.NewDocumentBuilder(). AppendInt64("x", 1). Build(), }, }, { name: "custom encode options", value: struct { Int int64 NilBytes []byte NilMap map[string]interface{} NilStrings []string ZeroStruct struct{ X int } `bson:"_,omitempty"` StringerMap map[bson.RawValue]bool BSONField string `json:"jsonField"` }{ Int: 1, NilBytes: nil, NilMap: nil, NilStrings: nil, StringerMap: map[bson.RawValue]bool{{}: true}, }, bsonOpts: &options.BSONOptions{ IntMinSize: true, NilByteSliceAsEmpty: true, NilMapAsEmpty: true, NilSliceAsEmpty: true, OmitZeroStruct: true, StringifyMapKeysWithFmt: true, UseJSONStructTags: true, }, want: bsoncore.Value{ Type: bson.TypeEmbeddedDocument, Data: bsoncore.NewDocumentBuilder(). AppendInt32("int", 1). AppendBinary("nilbytes", 0, []byte{}). AppendDocument("nilmap", bsoncore.NewDocumentBuilder().Build()). AppendArray("nilstrings", bsoncore.NewArrayBuilder().Build()). AppendDocument("stringermap", bsoncore.NewDocumentBuilder(). AppendBoolean("", true). Build()). AppendString("jsonField", ""). Build(), }, }, } for _, tc := range testCases { tc := tc // Capture range variable. t.Run(tc.name, func(t *testing.T) { t.Parallel() got, err := marshalValue(tc.value, tc.bsonOpts, tc.registry) assert.EqualBSON(t, tc.want, got) assert.Equal(t, tc.wantErr, err, "expected and actual error do not match") }) } } var _ bsoncodec.ValueMarshaler = bvMarsh{} type bvMarsh struct { t bsontype.Type data []byte err error } func (b bvMarsh) MarshalBSONValue() (bsontype.Type, []byte, error) { return b.t, b.data, b.err }	15.07 KB	2025-05-25 12:27
📄 mongocryptd.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "context" "os/exec" "strings" "time" "go.mongodb.org/mongo-driver/mongo/options" "go.mongodb.org/mongo-driver/mongo/readconcern" "go.mongodb.org/mongo-driver/mongo/readpref" "go.mongodb.org/mongo-driver/x/bsonx/bsoncore" ) const ( defaultServerSelectionTimeout = 10 * time.Second defaultURI = "mongodb://localhost:27020" defaultPath = "mongocryptd" serverSelectionTimeoutStr = "server selection error" ) var defaultTimeoutArgs = []string{"--idleShutdownTimeoutSecs=60"} var databaseOpts = options.Database().SetReadConcern(readconcern.New()).SetReadPreference(readpref.Primary()) type mongocryptdClient struct { bypassSpawn bool client Client path string spawnArgs []string } // newMongocryptdClient creates a client to mongocryptd. // newMongocryptdClient is expected to not be called if the crypt shared library is available. // The crypt shared library replaces all mongocryptd functionality. func newMongocryptdClient(opts options.AutoEncryptionOptions) (mongocryptdClient, error) { // create mcryptClient instance and spawn process if necessary var bypassSpawn bool var bypassAutoEncryption bool if bypass, ok := opts.ExtraOptions["mongocryptdBypassSpawn"]; ok { bypassSpawn = bypass.(bool) } if opts.BypassAutoEncryption != nil { bypassAutoEncryption = opts.BypassAutoEncryption } bypassQueryAnalysis := opts.BypassQueryAnalysis != nil && opts.BypassQueryAnalysis mc := &mongocryptdClient{ // mongocryptd should not be spawned if any of these conditions are true: // - mongocryptdBypassSpawn is passed // - bypassAutoEncryption is true because mongocryptd is not used during decryption // - bypassQueryAnalysis is true because mongocryptd is not used during decryption bypassSpawn: bypassSpawn \|\| bypassAutoEncryption \|\| bypassQueryAnalysis, } if !mc.bypassSpawn { mc.path, mc.spawnArgs = createSpawnArgs(opts.ExtraOptions) if err := mc.spawnProcess(); err != nil { return nil, err } } // get connection string uri := defaultURI if u, ok := opts.ExtraOptions["mongocryptdURI"]; ok { uri = u.(string) } // create client client, err := NewClient(options.Client().ApplyURI(uri).SetServerSelectionTimeout(defaultServerSelectionTimeout)) if err != nil { return nil, err } mc.client = client return mc, nil } // markCommand executes the given command on mongocryptd. func (mc mongocryptdClient) markCommand(ctx context.Context, dbName string, cmd bsoncore.Document) (bsoncore.Document, error) { // Remove the explicit session from the context if one is set. // The explicit session will be from a different client. // If an explicit session is set, it is applied after automatic encryption. ctx = NewSessionContext(ctx, nil) db := mc.client.Database(dbName, databaseOpts) res, err := db.RunCommand(ctx, cmd).Raw() // propagate original result if err == nil { return bsoncore.Document(res), nil } // wrap original error if mc.bypassSpawn \|\| !strings.Contains(err.Error(), serverSelectionTimeoutStr) { return nil, MongocryptdError{Wrapped: err} } // re-spawn and retry if err = mc.spawnProcess(); err != nil { return nil, err } res, err = db.RunCommand(ctx, cmd).Raw() if err != nil { return nil, MongocryptdError{Wrapped: err} } return bsoncore.Document(res), nil } // connect connects the underlying Client instance. This must be called before performing any mark operations. func (mc mongocryptdClient) connect(ctx context.Context) error { return mc.client.Connect(ctx) } // disconnect disconnects the underlying Client instance. This should be called after all operations have completed. func (mc mongocryptdClient) disconnect(ctx context.Context) error { return mc.client.Disconnect(ctx) } func (mc mongocryptdClient) spawnProcess() error { // Ignore gosec warning about subprocess launched with externally-provided path variable. / #nosec G204 */ cmd := exec.Command(mc.path, mc.spawnArgs...) cmd.Stdout = nil cmd.Stderr = nil return cmd.Start() } // createSpawnArgs creates arguments to spawn mcryptClient. It returns the path and a slice of arguments. func createSpawnArgs(opts map[string]interface{}) (string, []string) { var spawnArgs []string // get command path path := defaultPath if p, ok := opts["mongocryptdPath"]; ok { path = p.(string) } // add specified options if sa, ok := opts["mongocryptdSpawnArgs"]; ok { spawnArgs = append(spawnArgs, sa.([]string)...) } // add timeout options if necessary var foundTimeout bool for _, arg := range spawnArgs { // need to use HasPrefix instead of doing an exact equality check because both // mongocryptd supports both [--idleShutdownTimeoutSecs, 0] and [--idleShutdownTimeoutSecs=0] if strings.HasPrefix(arg, "--idleShutdownTimeoutSecs") { foundTimeout = true break } } if !foundTimeout { spawnArgs = append(spawnArgs, defaultTimeoutArgs...) } return path, spawnArgs }	5.12 KB	2025-05-25 12:27
📄 ocsp_test.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "crypto/tls" "os" "runtime" "strconv" "testing" "time" "go.mongodb.org/mongo-driver/internal/assert" "go.mongodb.org/mongo-driver/internal/integtest" "go.mongodb.org/mongo-driver/mongo/options" "go.mongodb.org/mongo-driver/mongo/readpref" ) func TestOCSP(t testing.T) { successEnvVar := os.Getenv("OCSP_TLS_SHOULD_SUCCEED") if successEnvVar == "" { t.Skip("skipping because OCSP_TLS_SHOULD_SUCCEED not set") } shouldSucceed, err := strconv.ParseBool(successEnvVar) assert.Nil(t, err, "invalid value for OCSP_TLS_SHOULD_SUCCEED; expected true or false, got %v", successEnvVar) cs := integtest.ConnString(t) t.Run("tls", func(t testing.T) { clientOpts := createOCSPClientOptions(cs.Original) client, err := Connect(bgCtx, clientOpts) assert.Nil(t, err, "Connect error: %v", err) defer func() { _ = client.Disconnect(bgCtx) }() err = client.Ping(bgCtx, readpref.Primary()) if shouldSucceed { assert.Nil(t, err, "Ping error: %v", err) return } // Log the error we got so it's visible in Evergreen and we can verify the tests are running as expected there. t.Logf("got Ping error: %v\n", err) assert.NotNil(t, err, "expected Ping error, got nil") }) t.Run("tlsInsecure", func(t testing.T) { clientOpts := createInsecureOCSPClientOptions(cs.Original) client, err := Connect(bgCtx, clientOpts) assert.Nil(t, err, "Connect error: %v", err) defer func() { _ = client.Disconnect(bgCtx) }() err = client.Ping(bgCtx, readpref.Primary()) assert.Nil(t, err, "Ping error: %v", err) }) } func createOCSPClientOptions(uri string) options.ClientOptions { opts := options.Client().ApplyURI(uri) timeout := 500 * time.Millisecond if runtime.GOOS == "windows" { // Non-stapled OCSP endpoint checks are slow on Windows. timeout = 5 * time.Second } opts.SetServerSelectionTimeout(timeout) return opts } func createInsecureOCSPClientOptions(uri string) *options.ClientOptions { opts := createOCSPClientOptions(uri) if opts.TLSConfig != nil { opts.TLSConfig.InsecureSkipVerify = true return opts } return opts.SetTLSConfig(&tls.Config{ InsecureSkipVerify: true, }) }	2.37 KB	2025-05-25 12:27
📁 options	-	2025-05-25 12:27
📄 read_write_concern_spec_test.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "bytes" "errors" "io/ioutil" "path" "reflect" "testing" "time" "go.mongodb.org/mongo-driver/bson" "go.mongodb.org/mongo-driver/bson/bsontype" "go.mongodb.org/mongo-driver/internal/assert" "go.mongodb.org/mongo-driver/mongo/readconcern" "go.mongodb.org/mongo-driver/mongo/writeconcern" "go.mongodb.org/mongo-driver/x/bsonx/bsoncore" "go.mongodb.org/mongo-driver/x/mongo/driver/connstring" ) const ( readWriteConcernTestsDir = "../testdata/read-write-concern" connstringTestsDir = "connection-string" documentTestsDir = "document" ) var ( serverDefaultConcern = []byte{5, 0, 0, 0, 0} // server default read concern and write concern is empty document specTestRegistry = bson.NewRegistryBuilder(). RegisterTypeMapEntry(bson.TypeEmbeddedDocument, reflect.TypeOf(bson.Raw{})).Build() ) type connectionStringTestFile struct { Tests []connectionStringTest `bson:"tests"` } type connectionStringTest struct { Description string `bson:"description"` URI string `bson:"uri"` Valid bool `bson:"valid"` ReadConcern bson.Raw `bson:"readConcern"` WriteConcern bson.Raw `bson:"writeConcern"` } type documentTestFile struct { Tests []documentTest `bson:"tests"` } type documentTest struct { Description string `bson:"description"` Valid bool `bson:"valid"` ReadConcern bson.Raw `bson:"readConcern"` ReadConcernDocument bson.Raw `bson:"readConcernDocument"` WriteConcern bson.Raw `bson:"writeConcern"` WriteConcernDocument bson.Raw `bson:"writeConcernDocument"` IsServerDefault bool `bson:"isServerDefault"` IsAcknowledged bool `bson:"isAcknowledged"` } func TestReadWriteConcernSpec(t testing.T) { t.Run("connstring", func(t testing.T) { for _, file := range jsonFilesInDir(t, path.Join(readWriteConcernTestsDir, connstringTestsDir)) { t.Run(file, func(t testing.T) { runConnectionStringTestFile(t, path.Join(readWriteConcernTestsDir, connstringTestsDir, file)) }) } }) t.Run("document", func(t testing.T) { for _, file := range jsonFilesInDir(t, path.Join(readWriteConcernTestsDir, documentTestsDir)) { t.Run(file, func(t testing.T) { runDocumentTestFile(t, path.Join(readWriteConcernTestsDir, documentTestsDir, file)) }) } }) } func runConnectionStringTestFile(t testing.T, filePath string) { content, err := ioutil.ReadFile(filePath) assert.Nil(t, err, "ReadFile error for %v: %v", filePath, err) var testFile connectionStringTestFile err = bson.UnmarshalExtJSONWithRegistry(specTestRegistry, content, false, &testFile) assert.Nil(t, err, "UnmarshalExtJSONWithRegistry error: %v", err) for _, test := range testFile.Tests { t.Run(test.Description, func(t testing.T) { runConnectionStringTest(t, test) }) } } func runConnectionStringTest(t testing.T, test connectionStringTest) { cs, err := connstring.ParseAndValidate(test.URI) if !test.Valid { assert.NotNil(t, err, "expected Parse error, got nil") return } assert.Nil(t, err, "Parse error: %v", err) if test.ReadConcern != nil { expected := readConcernFromRaw(t, test.ReadConcern) assert.Equal(t, expected.GetLevel(), cs.ReadConcernLevel, "expected level %v, got %v", expected.GetLevel(), cs.ReadConcernLevel) } if test.WriteConcern != nil { expectedWc := writeConcernFromRaw(t, test.WriteConcern) if expectedWc.wSet { expected := expectedWc.GetW() if _, ok := expected.(int); ok { assert.True(t, cs.WNumberSet, "expected WNumberSet, got false") assert.Equal(t, expected, cs.WNumber, "expected w value %v, got %v", expected, cs.WNumber) } else { assert.False(t, cs.WNumberSet, "expected WNumberSet to be false, got true") assert.Equal(t, expected, cs.WString, "expected w value %v, got %v", expected, cs.WString) } } if expectedWc.timeoutSet { assert.True(t, cs.WTimeoutSet, "expected WTimeoutSet, got false") assert.Equal(t, expectedWc.GetWTimeout(), cs.WTimeout, "expected timeout value %v, got %v", expectedWc.GetWTimeout(), cs.WTimeout) } if expectedWc.jSet { assert.True(t, cs.JSet, "expected JSet, got false") assert.Equal(t, expectedWc.GetJ(), cs.J, "expected j value %v, got %v", expectedWc.GetJ(), cs.J) } } } func runDocumentTestFile(t testing.T, filePath string) { content, err := ioutil.ReadFile(filePath) assert.Nil(t, err, "ReadFile error: %v", err) var testFile documentTestFile err = bson.UnmarshalExtJSONWithRegistry(specTestRegistry, content, false, &testFile) assert.Nil(t, err, "UnmarshalExtJSONWithRegistry error: %v", err) for _, test := range testFile.Tests { t.Run(test.Description, func(t testing.T) { runDocumentTest(t, test) }) } } func runDocumentTest(t testing.T, test documentTest) { if test.ReadConcern != nil { _, actual, err := readConcernFromRaw(t, test.ReadConcern).MarshalBSONValue() if !test.Valid { assert.NotNil(t, err, "expected MarshalBSONValue error, got nil") } else { assert.Nil(t, err, "MarshalBSONValue error: %v", err) compareDocuments(t, test.ReadConcernDocument, actual) } if test.IsServerDefault != nil { gotServerDefault := bytes.Equal(actual, serverDefaultConcern) assert.Equal(t, test.IsServerDefault, gotServerDefault, "expected server default read concern, got %s", actual) } } if test.WriteConcern != nil { actualWc := writeConcernFromRaw(t, test.WriteConcern) _, actual, err := actualWc.MarshalBSONValue() if !test.Valid { assert.NotNil(t, err, "expected MarshalBSONValue error, got nil") return } if test.IsAcknowledged != nil { actualAck := actualWc.Acknowledged() assert.Equal(t, test.IsAcknowledged, actualAck, "expected acknowledged %v, got %v", test.IsAcknowledged, actualAck) } expected := test.WriteConcernDocument if errors.Is(err, writeconcern.ErrEmptyWriteConcern) { elems, _ := expected.Elements() if len(elems) == 0 { assert.NotNil(t, test.IsServerDefault, "expected write concern %s, got empty", expected) assert.True(t, test.IsServerDefault, "expected write concern %s, got empty", expected) return } if _, jErr := expected.LookupErr("j"); jErr == nil && len(elems) == 1 { return } } assert.Nil(t, err, "MarshalBSONValue error: %v", err) if jVal, err := expected.LookupErr("j"); err == nil && !jVal.Boolean() { actual = actual[:len(actual)-1] actual = bsoncore.AppendBooleanElement(actual, "j", false) actual, _ = bsoncore.AppendDocumentEnd(actual, 0) } compareDocuments(t, expected, actual) } } func readConcernFromRaw(t testing.T, rc bson.Raw) readconcern.ReadConcern { t.Helper() var opts []readconcern.Option elems, _ := rc.Elements() for _, elem := range elems { key := elem.Key() val := elem.Value() switch key { case "level": opts = append(opts, readconcern.Level(val.StringValue())) default: t.Fatalf("unrecognized read concern field %v", key) } } return readconcern.New(opts...) } type writeConcern struct { writeconcern.WriteConcern jSet bool wSet bool timeoutSet bool } func writeConcernFromRaw(t testing.T, wcRaw bson.Raw) writeConcern { var wc writeConcern var opts []writeconcern.Option elems, _ := wcRaw.Elements() for _, elem := range elems { key := elem.Key() val := elem.Value() switch key { case "w": wc.wSet = true switch val.Type { case bsontype.Int32: w := int(val.Int32()) opts = append(opts, writeconcern.W(w)) case bsontype.String: opts = append(opts, writeconcern.WTagSet(val.StringValue())) default: t.Fatalf("unexpected type for w: %v", val.Type) } case "wtimeoutMS": wc.timeoutSet = true timeout := time.Duration(val.Int32()) time.Millisecond opts = append(opts, writeconcern.WTimeout(timeout)) case "journal": wc.jSet = true j := val.Boolean() opts = append(opts, writeconcern.J(j)) default: t.Fatalf("unrecognized write concern field: %v", key) } } wc.WriteConcern = writeconcern.New(opts...) return wc } // generate a slice of all JSON file names in a directory func jsonFilesInDir(t *testing.T, dir string) []string { t.Helper() files := make([]string, 0) entries, err := ioutil.ReadDir(dir) assert.Nil(t, err, "unable to read json file: %v", err) for _, entry := range entries { if entry.IsDir() \|\| path.Ext(entry.Name()) != ".json" { continue } files = append(files, entry.Name()) } return files }	8.53 KB	2025-05-25 12:27
📁 readconcern	-	2025-05-25 12:27
📁 readpref	-	2025-05-25 12:27
📄 results.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "fmt" "go.mongodb.org/mongo-driver/bson" "go.mongodb.org/mongo-driver/bson/primitive" "go.mongodb.org/mongo-driver/x/mongo/driver/operation" ) // BulkWriteResult is the result type returned by a BulkWrite operation. 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{} } // InsertOneResult is the result type returned by an InsertOne operation. type InsertOneResult struct { // The _id of the inserted document. A value generated by the driver will be of type primitive.ObjectID. InsertedID interface{} } // InsertManyResult is a result type returned by an InsertMany operation. type InsertManyResult struct { // The _id values of the inserted documents. Values generated by the driver will be of type primitive.ObjectID. InsertedIDs []interface{} } // TODO(GODRIVER-2367): Remove the BSON struct tags on DeleteResult. // DeleteResult is the result type returned by DeleteOne and DeleteMany operations. type DeleteResult struct { DeletedCount int64 `bson:"n"` // The number of documents deleted. } // RewrapManyDataKeyResult is the result of the bulk write operation used to update the key vault collection with // rewrapped data keys. type RewrapManyDataKeyResult struct { BulkWriteResult } // ListDatabasesResult is a result of a ListDatabases operation. 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 } func newListDatabasesResultFromOperation(res operation.ListDatabasesResult) ListDatabasesResult { var ldr ListDatabasesResult ldr.Databases = make([]DatabaseSpecification, 0, len(res.Databases)) for _, spec := range res.Databases { ldr.Databases = append( ldr.Databases, DatabaseSpecification{Name: spec.Name, SizeOnDisk: spec.SizeOnDisk, Empty: spec.Empty}, ) } ldr.TotalSize = res.TotalSize return ldr } // DatabaseSpecification contains information for a database. This type is returned as part of ListDatabasesResult. 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. } // UpdateResult is the result type returned from UpdateOne, UpdateMany, and ReplaceOne operations. 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. } // UnmarshalBSON implements the bson.Unmarshaler interface. // // Deprecated: Unmarshalling an UpdateResult directly from BSON is not supported and may produce // different results compared to running Update operations directly. func (result UpdateResult) UnmarshalBSON(b []byte) error { // TODO(GODRIVER-2367): Remove the ability to unmarshal BSON directly to an UpdateResult. elems, err := bson.Raw(b).Elements() if err != nil { return err } for _, elem := range elems { switch elem.Key() { case "n": switch elem.Value().Type { case bson.TypeInt32: result.MatchedCount = int64(elem.Value().Int32()) case bson.TypeInt64: result.MatchedCount = elem.Value().Int64() default: return fmt.Errorf("Received invalid type for n, should be Int32 or Int64, received %s", elem.Value().Type) } case "nModified": switch elem.Value().Type { case bson.TypeInt32: result.ModifiedCount = int64(elem.Value().Int32()) case bson.TypeInt64: result.ModifiedCount = elem.Value().Int64() default: return fmt.Errorf("Received invalid type for nModified, should be Int32 or Int64, received %s", elem.Value().Type) } case "upserted": switch elem.Value().Type { case bson.TypeArray: e, err := elem.Value().Array().IndexErr(0) if err != nil { break } if e.Value().Type != bson.TypeEmbeddedDocument { break } var d struct { ID interface{} `bson:"_id"` } err = bson.Unmarshal(e.Value().Document(), &d) if err != nil { return err } result.UpsertedID = d.ID default: return fmt.Errorf("Received invalid type for upserted, should be Array, received %s", elem.Value().Type) } } } return nil } // 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 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 } var _ bson.Unmarshaler = (IndexSpecification)(nil) type unmarshalIndexSpecification struct { Name string `bson:"name"` Namespace string `bson:"ns"` KeysDocument bson.Raw `bson:"key"` Version int32 `bson:"v"` ExpireAfterSeconds int32 `bson:"expireAfterSeconds"` Sparse bool `bson:"sparse"` Unique bool `bson:"unique"` Clustered bool `bson:"clustered"` } // UnmarshalBSON implements the bson.Unmarshaler interface. // // Deprecated: Unmarshaling an IndexSpecification from BSON will not be supported in Go Driver 2.0. func (i IndexSpecification) UnmarshalBSON(data []byte) error { var temp unmarshalIndexSpecification if err := bson.Unmarshal(data, &temp); err != nil { return err } i.Name = temp.Name i.Namespace = temp.Namespace i.KeysDocument = temp.KeysDocument i.Version = temp.Version i.ExpireAfterSeconds = temp.ExpireAfterSeconds i.Sparse = temp.Sparse i.Unique = temp.Unique i.Clustered = temp.Clustered return nil } // CollectionSpecification represents a collection in a database. This type is returned by the // Database.ListCollectionSpecifications function. 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 primitive.Binary with Subtype 4. UUID primitive.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. This will be nil if the NameOnly // option is used and for MongoDB versions < 3.4. IDIndex IndexSpecification } var _ bson.Unmarshaler = (CollectionSpecification)(nil) // unmarshalCollectionSpecification is used to unmarshal BSON bytes from a listCollections command into a // CollectionSpecification. type unmarshalCollectionSpecification struct { Name string `bson:"name"` Type string `bson:"type"` Info struct { ReadOnly bool `bson:"readOnly"` UUID primitive.Binary `bson:"uuid"` } `bson:"info"` Options bson.Raw `bson:"options"` IDIndex IndexSpecification `bson:"idIndex"` } // UnmarshalBSON implements the bson.Unmarshaler interface. // // Deprecated: Unmarshaling a CollectionSpecification from BSON will not be supported in Go Driver // 2.0. func (cs CollectionSpecification) UnmarshalBSON(data []byte) error { var temp unmarshalCollectionSpecification if err := bson.Unmarshal(data, &temp); err != nil { return err } cs.Name = temp.Name cs.Type = temp.Type if cs.Type == "" { // The "type" field is only present on 3.4+ because views were introduced in 3.4, so we implicitly set the // value to "collection" if it's empty. cs.Type = "collection" } if temp.Info != nil { cs.ReadOnly = temp.Info.ReadOnly cs.UUID = temp.Info.UUID } cs.Options = temp.Options cs.IDIndex = temp.IDIndex return nil }	9.45 KB	2025-05-25 12:27
📄 results_test.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "testing" "go.mongodb.org/mongo-driver/bson" "go.mongodb.org/mongo-driver/internal/assert" ) func TestResults(t testing.T) { t.Run("delete result", func(t testing.T) { // TODO(GODRIVER-2367): Do not test the ability to unmarshal BSON directly to a DeleteResult. t.Run("unmarshal into", func(t testing.T) { doc := bson.D{ {"n", int64(2)}, {"ok", int64(1)}, } b, err := bson.Marshal(doc) assert.Nil(t, err, "Marshal error: %v", err) var result DeleteResult err = bson.Unmarshal(b, &result) assert.Nil(t, err, "Unmarshal error: %v", err) assert.Equal(t, int64(2), result.DeletedCount, "expected DeletedCount 2, got %v", result.DeletedCount) }) // TODO(GODRIVER-2367): Do not test the ability to marshal a DeleteResult to BSON. t.Run("marshal from", func(t testing.T) { result := DeleteResult{DeletedCount: 1} buf, err := bson.Marshal(result) assert.Nil(t, err, "Marshal error: %v", err) var doc bson.D err = bson.Unmarshal(buf, &doc) assert.Nil(t, err, "Unmarshal error: %v", err) assert.Equal(t, 1, len(doc), "expected document length 1, got %v", len(doc)) for _, elem := range doc { if elem.Key != "n" { continue } n, ok := elem.Value.(int64) assert.True(t, ok, "expected n type %T, got %T", int64(0), elem.Value) assert.Equal(t, int64(1), n, "expected n 1, got %v", n) return } t.Fatal("key n not found in document") }) }) t.Run("update result", func(t testing.T) { // TODO(GODRIVER-2367): Do not test the ability to unmarshal BSON directly to an UpdateResult. t.Run("unmarshal into", func(t testing.T) { doc := bson.D{ {"n", 1}, {"nModified", 2}, {"upserted", bson.A{ bson.D{ {"index", 0}, {"_id", 3}, }, }}, } b, err := bson.Marshal(doc) assert.Nil(t, err, "Marshal error: %v", err) var result UpdateResult err = bson.Unmarshal(b, &result) assert.Nil(t, err, "Unmarshal error: %v", err) assert.Equal(t, int64(1), result.MatchedCount, "expected MatchedCount 1, got %v", result.MatchedCount) assert.Equal(t, int64(2), result.ModifiedCount, "expected ModifiedCount 2, got %v", result.ModifiedCount) upsertedID := result.UpsertedID.(int32) assert.Equal(t, int32(3), upsertedID, "expected upsertedID 3, got %v", upsertedID) }) }) }	2.56 KB	2025-05-25 12:27
📄 search_index_view.go // Copyright (C) MongoDB, Inc. 2023-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "context" "fmt" "strconv" "go.mongodb.org/mongo-driver/bson" "go.mongodb.org/mongo-driver/mongo/options" "go.mongodb.org/mongo-driver/mongo/writeconcern" "go.mongodb.org/mongo-driver/x/bsonx/bsoncore" "go.mongodb.org/mongo-driver/x/mongo/driver" "go.mongodb.org/mongo-driver/x/mongo/driver/operation" "go.mongodb.org/mongo-driver/x/mongo/driver/session" ) // 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(). type SearchIndexView struct { coll Collection } // SearchIndexModel represents a new search index to be created. 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.SearchIndexesOptions } // 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 (siv SearchIndexView) List( ctx context.Context, searchIdxOpts options.SearchIndexesOptions, opts ...options.ListSearchIndexesOptions, ) (Cursor, error) { if ctx == nil { ctx = context.Background() } index := bson.D{} if searchIdxOpts != nil && searchIdxOpts.Name != nil { index = bson.D{{"name", searchIdxOpts.Name}} } aggregateOpts := make([]options.AggregateOptions, len(opts)) for i, opt := range opts { aggregateOpts[i] = opt.AggregateOpts } return siv.coll.Aggregate(ctx, Pipeline{{{"$listSearchIndexes", index}}}, aggregateOpts...) } // 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 (siv SearchIndexView) CreateOne( ctx context.Context, model SearchIndexModel, opts ...options.CreateSearchIndexesOptions, ) (string, error) { names, err := siv.CreateMany(ctx, []SearchIndexModel{model}, opts...) if err != nil { return "", err } return names[0], nil } // 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 (siv SearchIndexView) CreateMany( ctx context.Context, models []SearchIndexModel, _ ...options.CreateSearchIndexesOptions, ) ([]string, error) { var indexes bsoncore.Document aidx, indexes := bsoncore.AppendArrayStart(indexes) for i, model := range models { if model.Definition == nil { return nil, fmt.Errorf("search index model definition cannot be nil") } definition, err := marshal(model.Definition, siv.coll.bsonOpts, siv.coll.registry) if err != nil { return nil, err } var iidx int32 iidx, indexes = bsoncore.AppendDocumentElementStart(indexes, strconv.Itoa(i)) if model.Options != nil && model.Options.Name != nil { indexes = bsoncore.AppendStringElement(indexes, "name", model.Options.Name) } indexes = bsoncore.AppendDocumentElement(indexes, "definition", definition) indexes, err = bsoncore.AppendDocumentEnd(indexes, iidx) if err != nil { return nil, err } } indexes, err := bsoncore.AppendArrayEnd(indexes, aidx) if err != nil { return nil, err } sess := sessionFromContext(ctx) if sess == nil && siv.coll.client.sessionPool != nil { sess = session.NewImplicitClientSession(siv.coll.client.sessionPool, siv.coll.client.id) defer sess.EndSession() } err = siv.coll.client.validSession(sess) if err != nil { return nil, err } wc := siv.coll.writeConcern if sess.TransactionRunning() { wc = nil } if !writeconcern.AckWrite(wc) { sess = nil } selector := makePinnedSelector(sess, siv.coll.writeSelector) op := operation.NewCreateSearchIndexes(indexes). Session(sess).WriteConcern(wc).ClusterClock(siv.coll.client.clock). Database(siv.coll.db.name).Collection(siv.coll.name).CommandMonitor(siv.coll.client.monitor). Deployment(siv.coll.client.deployment).ServerSelector(selector).ServerAPI(siv.coll.client.serverAPI). Timeout(siv.coll.client.timeout) err = op.Execute(ctx) if err != nil { _, err = processWriteError(err) return nil, err } indexesCreated := op.Result().IndexesCreated names := make([]string, 0, len(indexesCreated)) for _, index := range indexesCreated { names = append(names, index.Name) } return names, nil } // 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 (siv SearchIndexView) DropOne( ctx context.Context, name string, _ ...options.DropSearchIndexOptions, ) error { if name == "" { return ErrMultipleIndexDrop } if ctx == nil { ctx = context.Background() } sess := sessionFromContext(ctx) if sess == nil && siv.coll.client.sessionPool != nil { sess = session.NewImplicitClientSession(siv.coll.client.sessionPool, siv.coll.client.id) defer sess.EndSession() } err := siv.coll.client.validSession(sess) if err != nil { return err } wc := siv.coll.writeConcern if sess.TransactionRunning() { wc = nil } if !writeconcern.AckWrite(wc) { sess = nil } selector := makePinnedSelector(sess, siv.coll.writeSelector) op := operation.NewDropSearchIndex(name). Session(sess).WriteConcern(wc).CommandMonitor(siv.coll.client.monitor). ServerSelector(selector).ClusterClock(siv.coll.client.clock). Database(siv.coll.db.name).Collection(siv.coll.name). Deployment(siv.coll.client.deployment).ServerAPI(siv.coll.client.serverAPI). Timeout(siv.coll.client.timeout) err = op.Execute(ctx) if de, ok := err.(driver.Error); ok && de.NamespaceNotFound() { return nil } return err } // 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). func (siv SearchIndexView) UpdateOne( ctx context.Context, name string, definition interface{}, _ ...options.UpdateSearchIndexOptions, ) error { if definition == nil { return fmt.Errorf("search index definition cannot be nil") } indexDefinition, err := marshal(definition, siv.coll.bsonOpts, siv.coll.registry) if err != nil { return err } if ctx == nil { ctx = context.Background() } sess := sessionFromContext(ctx) if sess == nil && siv.coll.client.sessionPool != nil { sess = session.NewImplicitClientSession(siv.coll.client.sessionPool, siv.coll.client.id) defer sess.EndSession() } err = siv.coll.client.validSession(sess) if err != nil { return err } wc := siv.coll.writeConcern if sess.TransactionRunning() { wc = nil } if !writeconcern.AckWrite(wc) { sess = nil } selector := makePinnedSelector(sess, siv.coll.writeSelector) op := operation.NewUpdateSearchIndex(name, indexDefinition). Session(sess).WriteConcern(wc).CommandMonitor(siv.coll.client.monitor). ServerSelector(selector).ClusterClock(siv.coll.client.clock). Database(siv.coll.db.name).Collection(siv.coll.name). Deployment(siv.coll.client.deployment).ServerAPI(siv.coll.client.serverAPI). Timeout(siv.coll.client.timeout) return op.Execute(ctx) }	8.33 KB	2025-05-25 12:27
📄 session.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "context" "errors" "time" "go.mongodb.org/mongo-driver/bson" "go.mongodb.org/mongo-driver/bson/primitive" "go.mongodb.org/mongo-driver/mongo/description" "go.mongodb.org/mongo-driver/mongo/options" "go.mongodb.org/mongo-driver/x/bsonx/bsoncore" "go.mongodb.org/mongo-driver/x/mongo/driver" "go.mongodb.org/mongo-driver/x/mongo/driver/operation" "go.mongodb.org/mongo-driver/x/mongo/driver/session" ) // ErrWrongClient is returned when a user attempts to pass in a session created by a different client than // the method call is using. var ErrWrongClient = errors.New("session was not created by this client") var withTransactionTimeout = 120 * time.Second // SessionContext combines the context.Context and mongo.Session interfaces. It should be used as the Context arguments // to operations that should be executed in a session. // // Implementations of SessionContext are not safe for concurrent use by multiple goroutines. // // There are two ways to create a SessionContext and use it in a session/transaction. The first is to use one of the // callback-based functions such as WithSession and UseSession. These functions create a SessionContext and pass it to // the provided callback. The other is to use NewSessionContext to explicitly create a SessionContext. type SessionContext interface { context.Context Session } type sessionContext struct { context.Context Session } type sessionKey struct { } // NewSessionContext creates a new SessionContext associated with the given Context and Session parameters. func NewSessionContext(ctx context.Context, sess Session) SessionContext { return &sessionContext{ Context: context.WithValue(ctx, sessionKey{}, sess), Session: sess, } } // 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 SessionFromContext(ctx context.Context) Session { val := ctx.Value(sessionKey{}) if val == nil { return nil } sess, ok := val.(Session) if !ok { return nil } return sess } // Session is an interface that represents 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. Custom implementations of this interface should not be used in production. 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. type Session interface { // StartTransaction starts a new transaction, configured with the given options, on this // session. This method returns an error if there is already a transaction in-progress for this // session. StartTransaction(...options.TransactionOptions) error // 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. AbortTransaction(context.Context) error // 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. CommitTransaction(context.Context) 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. WithTransaction(ctx context.Context, fn func(ctx SessionContext) (interface{}, error), opts ...options.TransactionOptions) (interface{}, error) // EndSession aborts any existing transactions and close the session. EndSession(context.Context) // ClusterTime returns the current cluster time document associated with the session. ClusterTime() bson.Raw // OperationTime returns the current operation time document associated with the session. OperationTime() primitive.Timestamp // Client the Client associated with the session. Client() Client // ID returns the current ID document associated with the session. The ID document is in the // form {"id": <BSON binary value>}. ID() bson.Raw // AdvanceClusterTime advances the cluster time for a session. This method returns an error if // the session has ended. AdvanceClusterTime(bson.Raw) error // AdvanceOperationTime advances the operation time for a session. This method returns an error // if the session has ended. AdvanceOperationTime(primitive.Timestamp) error session() } // XSession is an unstable interface for internal use only. // // Deprecated: This interface is unstable because it provides access to a session.Client object, which exists in the // "x" package. It should not be used by applications and may be changed or removed in any release. type XSession interface { ClientSession() session.Client } // sessionImpl represents a set of sequential operations executed by an application that are related in some way. type sessionImpl struct { clientSession session.Client client Client deployment driver.Deployment didCommitAfterStart bool // true if commit was called after start with no other operations } var _ Session = &sessionImpl{} var _ XSession = &sessionImpl{} // ClientSession implements the XSession interface. func (s sessionImpl) ClientSession() session.Client { return s.clientSession } // ID implements the Session interface. func (s sessionImpl) ID() bson.Raw { return bson.Raw(s.clientSession.SessionID) } // EndSession implements the Session interface. func (s sessionImpl) EndSession(ctx context.Context) { if s.clientSession.TransactionInProgress() { // ignore all errors aborting during an end session _ = s.AbortTransaction(ctx) } s.clientSession.EndSession() } // WithTransaction implements the Session interface. func (s sessionImpl) WithTransaction(ctx context.Context, fn func(ctx SessionContext) (interface{}, error), opts ...options.TransactionOptions) (interface{}, error) { timeout := time.NewTimer(withTransactionTimeout) defer timeout.Stop() var err error for { err = s.StartTransaction(opts...) if err != nil { return nil, err } res, err := fn(NewSessionContext(ctx, s)) if err != nil { if s.clientSession.TransactionRunning() { // Wrap the user-provided Context in a new one that behaves like context.Background() for deadlines and // cancellations, but forwards Value requests to the original one. _ = s.AbortTransaction(newBackgroundContext(ctx)) } select { case <-timeout.C: return nil, err default: } if errorHasLabel(err, driver.TransientTransactionError) { continue } return res, err } // Check if callback intentionally aborted and, if so, return immediately // with no error. err = s.clientSession.CheckAbortTransaction() if err != nil { return res, nil } // If context has errored, run AbortTransaction and return, as the CommitLoop // has no chance of succeeding. // // Aborting after a failed CommitTransaction is dangerous. Failed transaction // commits may unpin the session server-side, and subsequent transaction aborts // may run on a new mongos which could end up with commit and abort being executed // simultaneously. if ctx.Err() != nil { // Wrap the user-provided Context in a new one that behaves like context.Background() for deadlines and // cancellations, but forwards Value requests to the original one. _ = s.AbortTransaction(newBackgroundContext(ctx)) return nil, ctx.Err() } CommitLoop: for { err = s.CommitTransaction(newBackgroundContext(ctx)) // End when error is nil, as transaction has been committed. if err == nil { return res, nil } select { case <-timeout.C: return res, err default: } if cerr, ok := err.(CommandError); ok { if cerr.HasErrorLabel(driver.UnknownTransactionCommitResult) && !cerr.IsMaxTimeMSExpiredError() { continue } if cerr.HasErrorLabel(driver.TransientTransactionError) { break CommitLoop } } return res, err } } } // StartTransaction implements the Session interface. func (s sessionImpl) StartTransaction(opts ...options.TransactionOptions) error { err := s.clientSession.CheckStartTransaction() if err != nil { return err } s.didCommitAfterStart = false topts := options.MergeTransactionOptions(opts...) coreOpts := &session.TransactionOptions{ ReadConcern: topts.ReadConcern, ReadPreference: topts.ReadPreference, WriteConcern: topts.WriteConcern, MaxCommitTime: topts.MaxCommitTime, } return s.clientSession.StartTransaction(coreOpts) } // AbortTransaction implements the Session interface. func (s sessionImpl) AbortTransaction(ctx context.Context) error { err := s.clientSession.CheckAbortTransaction() if err != nil { return err } // Do not run the abort command if the transaction is in starting state if s.clientSession.TransactionStarting() \|\| s.didCommitAfterStart { return s.clientSession.AbortTransaction() } selector := makePinnedSelector(s.clientSession, description.WriteSelector()) s.clientSession.Aborting = true _ = operation.NewAbortTransaction().Session(s.clientSession).ClusterClock(s.client.clock).Database("admin"). Deployment(s.deployment).WriteConcern(s.clientSession.CurrentWc).ServerSelector(selector). Retry(driver.RetryOncePerCommand).CommandMonitor(s.client.monitor). RecoveryToken(bsoncore.Document(s.clientSession.RecoveryToken)).ServerAPI(s.client.serverAPI).Execute(ctx) s.clientSession.Aborting = false _ = s.clientSession.AbortTransaction() return nil } // CommitTransaction implements the Session interface. func (s sessionImpl) CommitTransaction(ctx context.Context) error { err := s.clientSession.CheckCommitTransaction() if err != nil { return err } // Do not run the commit command if the transaction is in started state if s.clientSession.TransactionStarting() \|\| s.didCommitAfterStart { s.didCommitAfterStart = true return s.clientSession.CommitTransaction() } if s.clientSession.TransactionCommitted() { s.clientSession.RetryingCommit = true } selector := makePinnedSelector(s.clientSession, description.WriteSelector()) s.clientSession.Committing = true op := operation.NewCommitTransaction(). Session(s.clientSession).ClusterClock(s.client.clock).Database("admin").Deployment(s.deployment). WriteConcern(s.clientSession.CurrentWc).ServerSelector(selector).Retry(driver.RetryOncePerCommand). CommandMonitor(s.client.monitor).RecoveryToken(bsoncore.Document(s.clientSession.RecoveryToken)). ServerAPI(s.client.serverAPI).MaxTime(s.clientSession.CurrentMct) err = op.Execute(ctx) // Return error without updating transaction state if it is a timeout, as the transaction has not // actually been committed. if IsTimeout(err) { return replaceErrors(err) } s.clientSession.Committing = false commitErr := s.clientSession.CommitTransaction() // We set the write concern to majority for subsequent calls to CommitTransaction. s.clientSession.UpdateCommitTransactionWriteConcern() if err != nil { return replaceErrors(err) } return commitErr } // ClusterTime implements the Session interface. func (s sessionImpl) ClusterTime() bson.Raw { return s.clientSession.ClusterTime } // AdvanceClusterTime implements the Session interface. func (s sessionImpl) AdvanceClusterTime(d bson.Raw) error { return s.clientSession.AdvanceClusterTime(d) } // OperationTime implements the Session interface. func (s sessionImpl) OperationTime() primitive.Timestamp { return s.clientSession.OperationTime } // AdvanceOperationTime implements the Session interface. func (s sessionImpl) AdvanceOperationTime(ts primitive.Timestamp) error { return s.clientSession.AdvanceOperationTime(ts) } // Client implements the Session interface. func (s sessionImpl) Client() Client { return s.client } // session implements the Session interface. func (sessionImpl) session() { } // sessionFromContext checks for a sessionImpl in the argued context and returns the session if it // exists func sessionFromContext(ctx context.Context) session.Client { s := ctx.Value(sessionKey{}) if ses, ok := s.(*sessionImpl); ses != nil && ok { return ses.clientSession } return nil }	13.7 KB	2025-05-25 12:27
📄 single_result.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "context" "errors" "fmt" "go.mongodb.org/mongo-driver/bson" "go.mongodb.org/mongo-driver/bson/bsoncodec" "go.mongodb.org/mongo-driver/mongo/options" ) // ErrNoDocuments is returned by SingleResult methods when the operation that created the SingleResult did not return // any documents. var ErrNoDocuments = errors.New("mongo: no documents in result") // 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. type SingleResult struct { ctx context.Context err error cur Cursor rdr bson.Raw bsonOpts options.BSONOptions reg bsoncodec.Registry } // 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.DefaultRegistry 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 NewSingleResultFromDocument(document interface{}, err error, registry bsoncodec.Registry) SingleResult { if document == nil { return &SingleResult{err: ErrNilDocument} } if registry == nil { registry = bson.DefaultRegistry } cur, createErr := NewCursorFromDocuments([]interface{}{document}, err, registry) if createErr != nil { return &SingleResult{err: createErr} } return &SingleResult{ cur: cur, err: err, reg: registry, } } // 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 (sr SingleResult) Decode(v interface{}) error { if sr.err != nil { return sr.err } if sr.reg == nil { return bson.ErrNilRegistry } if sr.err = sr.setRdrContents(); sr.err != nil { return sr.err } dec, err := getDecoder(sr.rdr, sr.bsonOpts, sr.reg) if err != nil { return fmt.Errorf("error configuring BSON decoder: %w", err) } return dec.Decode(v) } // 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). func (sr SingleResult) Raw() (bson.Raw, error) { if sr.err != nil { return sr.rdr, sr.err } if sr.err = sr.setRdrContents(); sr.err != nil { return nil, sr.err } return sr.rdr, nil } // DecodeBytes will return 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). // // Deprecated: Use [SingleResult.Raw] instead. func (sr SingleResult) DecodeBytes() (bson.Raw, error) { return sr.Raw() } // setRdrContents will set the contents of rdr by iterating the underlying cursor if necessary. func (sr SingleResult) setRdrContents() error { switch { case sr.err != nil: return sr.err case sr.rdr != nil: return nil case sr.cur != nil: defer sr.cur.Close(sr.ctx) if !sr.cur.Next(sr.ctx) { if err := sr.cur.Err(); err != nil { return err } return ErrNoDocuments } sr.rdr = sr.cur.Current return nil } return ErrNoDocuments } // 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 (sr SingleResult) Err() error { sr.err = sr.setRdrContents() return sr.err }	4.52 KB	2025-05-25 12:27
📄 single_result_test.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "context" "errors" "fmt" "testing" "go.mongodb.org/mongo-driver/bson" "go.mongodb.org/mongo-driver/internal/assert" "go.mongodb.org/mongo-driver/internal/require" "go.mongodb.org/mongo-driver/mongo/options" ) func TestSingleResult(t testing.T) { t.Run("Decode", func(t testing.T) { t.Run("decode twice", func(t testing.T) { // Test that Decode and Raw can be called more than once c, err := newCursor(newTestBatchCursor(1, 1), nil, bson.DefaultRegistry) assert.Nil(t, err, "newCursor error: %v", err) sr := &SingleResult{cur: c, reg: bson.DefaultRegistry} var firstDecode, secondDecode bson.Raw err = sr.Decode(&firstDecode) assert.Nil(t, err, "Decode error: %v", err) err = sr.Decode(&secondDecode) assert.Nil(t, err, "Decode error: %v", err) rawBytes, err := sr.Raw() assert.Nil(t, err, "Raw error: %v", err) assert.Equal(t, firstDecode, secondDecode, "expected contents %v, got %v", firstDecode, secondDecode) assert.Equal(t, firstDecode, rawBytes, "expected contents %v, got %v", firstDecode, rawBytes) }) t.Run("decode with error", func(t testing.T) { r := []byte("foo") sr := &SingleResult{rdr: r, err: errors.New("Raw error")} res, err := sr.Raw() resBytes := []byte(res) assert.Equal(t, r, resBytes, "expected contents %v, got %v", r, resBytes) assert.Equal(t, sr.err, err, "expected error %v, got %v", sr.err, err) }) t.Run("with BSONOptions", func(t testing.T) { c, err := newCursor(newTestBatchCursor(1, 1), nil, bson.DefaultRegistry) require.NoError(t, err, "newCursor error") sr := &SingleResult{ cur: c, bsonOpts: &options.BSONOptions{ UseJSONStructTags: true, }, reg: bson.DefaultRegistry, } type myDocument struct { A int32 `json:"foo"` } var got myDocument err = sr.Decode(&got) require.NoError(t, err, "Decode error") i := int32(0) want := myDocument{A: &i} assert.Equal(t, want, got, "expected and actual Decode results are different") }) }) t.Run("Err", func(t testing.T) { sr := &SingleResult{} assert.Equal(t, ErrNoDocuments, sr.Err(), "expected error %v, got %v", ErrNoDocuments, sr.Err()) }) } func TestNewSingleResultFromDocument(t testing.T) { // Mock a document returned by FindOne in SingleResult. t.Run("mock FindOne", func(t testing.T) { findOneResult := bson.D{{"_id", 2}, {"foo", "bar"}} res := NewSingleResultFromDocument(findOneResult, nil, nil) // Assert that first, decoded document is as expected. findOneResultBytes, err := bson.Marshal(findOneResult) assert.Nil(t, err, "Marshal error: %v", err) expectedRawBytes := bson.Raw(findOneResultBytes) rawBytes, err := res.Raw() assert.Nil(t, err, "Raw error: %v", err) assert.Equal(t, expectedRawBytes, rawBytes, "expected decoded SingleResult to be %v, got %v", expectedRawBytes, rawBytes) // Assert that RDR contents are set correctly after Decode. assert.NotNil(t, res.rdr, "expected non-nil rdr contents") assert.Equal(t, expectedRawBytes, res.rdr, "expected RDR contents to be %v, got %v", expectedRawBytes, res.rdr) // Assert that a call to cur.Next will return false, as there was only one document in // the slice passed to NewSingleResultFromDocument. next := res.cur.Next(context.Background()) assert.False(t, next, "expected call to Next to return false, got true") // Check for error on SingleResult. assert.Nil(t, res.Err(), "SingleResult error: %v", res.Err()) // Assert that a call to cur.Close will not fail. err = res.cur.Close(context.Background()) assert.Nil(t, err, "Close error: %v", err) }) // Mock an error in SingleResult. t.Run("mock FindOne with error", func(t testing.T) { mockErr := fmt.Errorf("mock error") res := NewSingleResultFromDocument(bson.D{}, mockErr, nil) // Assert that the raw bytes returns the mocked error. _, err := res.Raw() assert.NotNil(t, err, "expected Raw error, got nil") assert.Equal(t, mockErr, err, "expected error %v, got %v", mockErr, err) // Check for error on SingleResult. assert.NotNil(t, res.Err(), "expected SingleResult error, got nil") assert.Equal(t, mockErr, res.Err(), "expected SingleResult error %v, got %v", mockErr, res.Err()) // Assert that error is propagated to underlying cursor. assert.NotNil(t, res.cur.err, "expected underlying cursor, got nil") assert.Equal(t, mockErr, res.cur.err, "expected underlying cursor %v, got %v", mockErr, res.cur.err) }) }	4.66 KB	2025-05-25 12:27
📄 util.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo	284 B	2025-05-25 12:27
📄 with_transactions_test.go // Copyright (C) MongoDB, Inc. 2017-present. // // Licensed under the Apache License, Version 2.0 (the "License"); you may // not use this file except in compliance with the License. You may obtain // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 package mongo import ( "context" "errors" "fmt" "math" "os" "strconv" "strings" "testing" "time" "go.mongodb.org/mongo-driver/bson" "go.mongodb.org/mongo-driver/event" "go.mongodb.org/mongo-driver/internal/assert" "go.mongodb.org/mongo-driver/internal/integtest" "go.mongodb.org/mongo-driver/mongo/description" "go.mongodb.org/mongo-driver/mongo/options" "go.mongodb.org/mongo-driver/mongo/readpref" "go.mongodb.org/mongo-driver/mongo/writeconcern" "go.mongodb.org/mongo-driver/x/mongo/driver" "go.mongodb.org/mongo-driver/x/mongo/driver/topology" ) var ( connsCheckedOut int errorInterrupted int32 = 11601 ) func TestConvenientTransactions(t testing.T) { if testing.Short() { t.Skip("skipping integration test in short mode") } if os.Getenv("DOCKER_RUNNING") != "" { t.Skip("skipping test in docker environment") } client := setupConvenientTransactions(t) db := client.Database("TestConvenientTransactions") dbAdmin := client.Database("admin") defer func() { sessions := client.NumberSessionsInProgress() conns := connsCheckedOut err := dbAdmin.RunCommand(bgCtx, bson.D{ {"killAllSessions", bson.A{}}, }).Err() if err != nil { if ce, ok := err.(CommandError); !ok \|\| ce.Code != errorInterrupted { t.Fatalf("killAllSessions error: %v", err) } } _ = db.Drop(bgCtx) _ = client.Disconnect(bgCtx) assert.Equal(t, 0, sessions, "%v sessions checked out", sessions) assert.Equal(t, 0, conns, "%v connections checked out", conns) }() t.Run("callback raises custom error", func(t testing.T) { coll := db.Collection(t.Name()) _, err := coll.InsertOne(bgCtx, bson.D{{"x", 1}}) assert.Nil(t, err, "InsertOne error: %v", err) sess, err := client.StartSession() assert.Nil(t, err, "StartSession error: %v", err) defer sess.EndSession(context.Background()) testErr := errors.New("test error") _, err = sess.WithTransaction(context.Background(), func(SessionContext) (interface{}, error) { return nil, testErr }) assert.Equal(t, testErr, err, "expected error %v, got %v", testErr, err) }) t.Run("callback returns value", func(t testing.T) { coll := db.Collection(t.Name()) _, err := coll.InsertOne(bgCtx, bson.D{{"x", 1}}) assert.Nil(t, err, "InsertOne error: %v", err) sess, err := client.StartSession() assert.Nil(t, err, "StartSession error: %v", err) defer sess.EndSession(context.Background()) res, err := sess.WithTransaction(context.Background(), func(SessionContext) (interface{}, error) { return false, nil }) assert.Nil(t, err, "WithTransaction error: %v", err) resBool, ok := res.(bool) assert.True(t, ok, "expected result type %T, got %T", false, res) assert.False(t, resBool, "expected result false, got %v", resBool) }) t.Run("retry timeout enforced", func(t testing.T) { withTransactionTimeout = time.Second coll := db.Collection(t.Name()) _, err := coll.InsertOne(bgCtx, bson.D{{"x", 1}}) assert.Nil(t, err, "InsertOne error: %v", err) t.Run("transient transaction error", func(t testing.T) { sess, err := client.StartSession() assert.Nil(t, err, "StartSession error: %v", err) defer sess.EndSession(context.Background()) _, err = sess.WithTransaction(context.Background(), func(SessionContext) (interface{}, error) { return nil, CommandError{Name: "test Error", Labels: []string{driver.TransientTransactionError}} }) assert.NotNil(t, err, "expected WithTransaction error, got nil") cmdErr, ok := err.(CommandError) assert.True(t, ok, "expected error type %T, got %T", CommandError{}, err) assert.True(t, cmdErr.HasErrorLabel(driver.TransientTransactionError), "expected error with label %v, got %v", driver.TransientTransactionError, cmdErr) }) t.Run("unknown transaction commit result", func(t testing.T) { //set failpoint failpoint := bson.D{{"configureFailPoint", "failCommand"}, {"mode", "alwaysOn"}, {"data", bson.D{ {"failCommands", bson.A{"commitTransaction"}}, {"closeConnection", true}, }}, } err = dbAdmin.RunCommand(bgCtx, failpoint).Err() assert.Nil(t, err, "error setting failpoint: %v", err) defer func() { err = dbAdmin.RunCommand(bgCtx, bson.D{ {"configureFailPoint", "failCommand"}, {"mode", "off"}, }).Err() assert.Nil(t, err, "error turning off failpoint: %v", err) }() sess, err := client.StartSession() assert.Nil(t, err, "StartSession error: %v", err) defer sess.EndSession(context.Background()) _, err = sess.WithTransaction(context.Background(), func(ctx SessionContext) (interface{}, error) { _, err := coll.InsertOne(ctx, bson.D{{"x", 1}}) return nil, err }) assert.NotNil(t, err, "expected WithTransaction error, got nil") cmdErr, ok := err.(CommandError) assert.True(t, ok, "expected error type %T, got %T", CommandError{}, err) assert.True(t, cmdErr.HasErrorLabel(driver.UnknownTransactionCommitResult), "expected error with label %v, got %v", driver.UnknownTransactionCommitResult, cmdErr) }) t.Run("commit transient transaction error", func(t testing.T) { //set failpoint failpoint := bson.D{{"configureFailPoint", "failCommand"}, {"mode", "alwaysOn"}, {"data", bson.D{ {"failCommands", bson.A{"commitTransaction"}}, {"errorCode", 251}, }}, } err = dbAdmin.RunCommand(bgCtx, failpoint).Err() assert.Nil(t, err, "error setting failpoint: %v", err) defer func() { err = dbAdmin.RunCommand(bgCtx, bson.D{ {"configureFailPoint", "failCommand"}, {"mode", "off"}, }).Err() assert.Nil(t, err, "error turning off failpoint: %v", err) }() sess, err := client.StartSession() assert.Nil(t, err, "StartSession error: %v", err) defer sess.EndSession(context.Background()) _, err = sess.WithTransaction(context.Background(), func(ctx SessionContext) (interface{}, error) { _, err := coll.InsertOne(ctx, bson.D{{"x", 1}}) return nil, err }) assert.NotNil(t, err, "expected WithTransaction error, got nil") cmdErr, ok := err.(CommandError) assert.True(t, ok, "expected error type %T, got %T", CommandError{}, err) assert.True(t, cmdErr.HasErrorLabel(driver.TransientTransactionError), "expected error with label %v, got %v", driver.TransientTransactionError, cmdErr) }) }) t.Run("abortTransaction does not time out", func(t testing.T) { // Create a special CommandMonitor that only records information about abortTransaction events and also // records the Context used in the CommandStartedEvent listener. var abortStarted []event.CommandStartedEvent var abortSucceeded []event.CommandSucceededEvent var abortFailed []event.CommandFailedEvent var abortCtx context.Context monitor := &event.CommandMonitor{ Started: func(ctx context.Context, evt event.CommandStartedEvent) { if evt.CommandName == "abortTransaction" { abortStarted = append(abortStarted, evt) if abortCtx == nil { abortCtx = ctx } } }, Succeeded: func(_ context.Context, evt event.CommandSucceededEvent) { if evt.CommandName == "abortTransaction" { abortSucceeded = append(abortSucceeded, evt) } }, Failed: func(_ context.Context, evt event.CommandFailedEvent) { if evt.CommandName == "abortTransaction" { abortFailed = append(abortFailed, evt) } }, } // Set up a new Client using the command monitor defined above get a handle to a collection. The collection // needs to be explicitly created on the server because implicit collection creation is not allowed in // transactions for server versions <= 4.2. client := setupConvenientTransactions(t, options.Client().SetMonitor(monitor)) db := client.Database("foo") coll := db.Collection("bar") err := db.RunCommand(bgCtx, bson.D{{"create", coll.Name()}}).Err() assert.Nil(t, err, "error creating collection on server: %v\n", err) sess, err := client.StartSession() assert.Nil(t, err, "StartSession error: %v", err) defer func() { sess.EndSession(bgCtx) _ = coll.Drop(bgCtx) _ = client.Disconnect(bgCtx) }() // Create a cancellable Context with a value for ctxKey. type ctxKey struct{} ctx, cancel := context.WithCancel(context.WithValue(context.Background(), ctxKey{}, "foobar")) defer cancel() // The WithTransaction callback does an Insert to ensure that the txn has been started server-side. After the // insert succeeds, it cancels the Context created above and returns a non-retryable error, which forces // WithTransaction to abort the txn. callbackErr := errors.New("error") callback := func(sc SessionContext) (interface{}, error) { _, err = coll.InsertOne(sc, bson.D{{"x", 1}}) if err != nil { return nil, err } cancel() return nil, callbackErr } _, err = sess.WithTransaction(ctx, callback) assert.Equal(t, callbackErr, err, "expected WithTransaction error %v, got %v", callbackErr, err) // Assert that abortTransaction was sent once and succeede. assert.Equal(t, 1, len(abortStarted), "expected 1 abortTransaction started event, got %d", len(abortStarted)) assert.Equal(t, 1, len(abortSucceeded), "expected 1 abortTransaction succeeded event, got %d", len(abortSucceeded)) assert.Equal(t, 0, len(abortFailed), "expected 0 abortTransaction failed event, got %d", len(abortFailed)) // Assert that the Context propagated to the CommandStartedEvent listener for abortTransaction contained a value // for ctxKey. ctxValue, ok := abortCtx.Value(ctxKey{}).(string) assert.True(t, ok, "expected context for abortTransaction to contain ctxKey") assert.Equal(t, "foobar", ctxValue, "expected value for ctxKey to be 'world', got %s", ctxValue) }) t.Run("commitTransaction timeout allows abortTransaction", func(t testing.T) { // Create a special CommandMonitor that only records information about abortTransaction events. var abortStarted []event.CommandStartedEvent var abortSucceeded []event.CommandSucceededEvent var abortFailed []event.CommandFailedEvent monitor := &event.CommandMonitor{ Started: func(ctx context.Context, evt event.CommandStartedEvent) { if evt.CommandName == "abortTransaction" { abortStarted = append(abortStarted, evt) } }, Succeeded: func(_ context.Context, evt event.CommandSucceededEvent) { if evt.CommandName == "abortTransaction" { abortSucceeded = append(abortSucceeded, evt) } }, Failed: func(_ context.Context, evt event.CommandFailedEvent) { if evt.CommandName == "abortTransaction" { abortFailed = append(abortFailed, evt) } }, } // Set up a new Client using the command monitor defined above get a handle to a collection. The collection // needs to be explicitly created on the server because implicit collection creation is not allowed in // transactions for server versions <= 4.2. client := setupConvenientTransactions(t, options.Client().SetMonitor(monitor)) db := client.Database("foo") coll := db.Collection("test") defer func() { _ = coll.Drop(bgCtx) }() err := db.RunCommand(bgCtx, bson.D{{"create", coll.Name()}}).Err() assert.Nil(t, err, "error creating collection on server: %v", err) // Start session. session, err := client.StartSession() defer session.EndSession(bgCtx) assert.Nil(t, err, "StartSession error: %v", err) _ = WithSession(bgCtx, session, func(sessionContext SessionContext) error { // Start transaction. err = session.StartTransaction() assert.Nil(t, err, "StartTransaction error: %v", err) // Insert a document. _, err := coll.InsertOne(sessionContext, bson.D{{"val", 17}}) assert.Nil(t, err, "InsertOne error: %v", err) // Set a timeout of 0 for commitTransaction. commitTimeoutCtx, commitCancel := context.WithTimeout(sessionContext, 0) defer commitCancel() // CommitTransaction results in context.DeadlineExceeded. commitErr := session.CommitTransaction(commitTimeoutCtx) assert.True(t, IsTimeout(commitErr), "expected timeout error error; got %v", commitErr) // Assert session state is not Committed. clientSession := session.(XSession).ClientSession() assert.False(t, clientSession.TransactionCommitted(), "expected session state to not be Committed") // AbortTransaction without error. abortErr := session.AbortTransaction(context.Background()) assert.Nil(t, abortErr, "AbortTransaction error: %v", abortErr) // Assert that AbortTransaction was started once and succeeded. assert.Equal(t, 1, len(abortStarted), "expected 1 abortTransaction started event, got %d", len(abortStarted)) assert.Equal(t, 1, len(abortSucceeded), "expected 1 abortTransaction succeeded event, got %d", len(abortSucceeded)) assert.Equal(t, 0, len(abortFailed), "expected 0 abortTransaction failed events, got %d", len(abortFailed)) return nil }) }) t.Run("context error before commitTransaction does not retry and aborts", func(t testing.T) { withTransactionTimeout = 2 * time.Second // Create a special CommandMonitor that only records information about abortTransaction events. var abortStarted []event.CommandStartedEvent var abortSucceeded []event.CommandSucceededEvent var abortFailed []event.CommandFailedEvent monitor := &event.CommandMonitor{ Started: func(ctx context.Context, evt event.CommandStartedEvent) { if evt.CommandName == "abortTransaction" { abortStarted = append(abortStarted, evt) } }, Succeeded: func(_ context.Context, evt event.CommandSucceededEvent) { if evt.CommandName == "abortTransaction" { abortSucceeded = append(abortSucceeded, evt) } }, Failed: func(_ context.Context, evt event.CommandFailedEvent) { if evt.CommandName == "abortTransaction" { abortFailed = append(abortFailed, evt) } }, } // Set up a new Client using the command monitor defined above get a handle to a collection. The collection // needs to be explicitly created on the server because implicit collection creation is not allowed in // transactions for server versions <= 4.2. client := setupConvenientTransactions(t, options.Client().SetMonitor(monitor)) db := client.Database("foo") coll := db.Collection("test") // Explicitly create the collection on server because implicit collection creation is not allowed in // transactions for server versions <= 4.2. err := db.RunCommand(bgCtx, bson.D{{"create", coll.Name()}}).Err() assert.Nil(t, err, "error creating collection on server: %v", err) defer func() { _ = coll.Drop(bgCtx) }() // Start session. sess, err := client.StartSession() assert.Nil(t, err, "StartSession error: %v", err) defer sess.EndSession(context.Background()) // Defer running killAllSessions to manually close open transaction. defer func() { err := dbAdmin.RunCommand(bgCtx, bson.D{ {"killAllSessions", bson.A{}}, }).Err() if err != nil { if ce, ok := err.(CommandError); !ok \|\| ce.Code != errorInterrupted { t.Fatalf("killAllSessions error: %v", err) } } }() // Insert a document within a session and manually cancel context before // "commitTransaction" can be sent. callback := func(ctx context.Context) { transactionCtx, cancel := context.WithCancel(ctx) _, _ = sess.WithTransaction(transactionCtx, func(ctx SessionContext) (interface{}, error) { _, err := coll.InsertOne(ctx, bson.M{"x": 1}) assert.Nil(t, err, "InsertOne error: %v", err) cancel() return nil, nil }) } // Assert that transaction is canceled within 500ms and not 2 seconds. assert.Soon(t, callback, 500time.Millisecond) // Assert that AbortTransaction was started once and succeeded. assert.Equal(t, 1, len(abortStarted), "expected 1 abortTransaction started event, got %d", len(abortStarted)) assert.Equal(t, 1, len(abortSucceeded), "expected 1 abortTransaction succeeded event, got %d", len(abortSucceeded)) assert.Equal(t, 0, len(abortFailed), "expected 0 abortTransaction failed events, got %d", len(abortFailed)) }) t.Run("wrapped transient transaction error retried", func(t testing.T) { sess, err := client.StartSession() assert.Nil(t, err, "StartSession error: %v", err) defer sess.EndSession(context.Background()) // returnError tracks whether or not the callback is being retried returnError := true res, err := sess.WithTransaction(context.Background(), func(SessionContext) (interface{}, error) { if returnError { returnError = false return nil, fmt.Errorf("%w", CommandError{ Name: "test Error", Labels: []string{driver.TransientTransactionError}, }, ) } return false, nil }) assert.Nil(t, err, "WithTransaction error: %v", err) resBool, ok := res.(bool) assert.True(t, ok, "expected result type %T, got %T", false, res) assert.False(t, resBool, "expected result false, got %v", resBool) }) t.Run("expired context before callback does not retry", func(t testing.T) { withTransactionTimeout = 2 time.Second coll := db.Collection("test") // Explicitly create the collection on server because implicit collection creation is not allowed in // transactions for server versions <= 4.2. err := db.RunCommand(bgCtx, bson.D{{"create", coll.Name()}}).Err() assert.Nil(t, err, "error creating collection on server: %v", err) defer func() { _ = coll.Drop(bgCtx) }() sess, err := client.StartSession() assert.Nil(t, err, "StartSession error: %v", err) defer sess.EndSession(context.Background()) callback := func(ctx context.Context) { // Create transaction context with short timeout. withTransactionContext, cancel := context.WithTimeout(ctx, time.Nanosecond) defer cancel() _, _ = sess.WithTransaction(withTransactionContext, func(ctx SessionContext) (interface{}, error) { _, err := coll.InsertOne(ctx, bson.D{{}}) return nil, err }) } // Assert that transaction fails within 500ms and not 2 seconds. assert.Soon(t, callback, 500time.Millisecond) }) t.Run("canceled context before callback does not retry", func(t testing.T) { withTransactionTimeout = 2 * time.Second coll := db.Collection("test") // Explicitly create the collection on server because implicit collection creation is not allowed in // transactions for server versions <= 4.2. err := db.RunCommand(bgCtx, bson.D{{"create", coll.Name()}}).Err() assert.Nil(t, err, "error creating collection on server: %v", err) defer func() { _ = coll.Drop(bgCtx) }() sess, err := client.StartSession() assert.Nil(t, err, "StartSession error: %v", err) defer sess.EndSession(context.Background()) callback := func(ctx context.Context) { // Create transaction context and cancel it immediately. withTransactionContext, cancel := context.WithTimeout(ctx, 2time.Second) cancel() _, _ = sess.WithTransaction(withTransactionContext, func(ctx SessionContext) (interface{}, error) { _, err := coll.InsertOne(ctx, bson.D{{}}) return nil, err }) } // Assert that transaction fails within 500ms and not 2 seconds. assert.Soon(t, callback, 500time.Millisecond) }) t.Run("slow operation in callback retries", func(t testing.T) { withTransactionTimeout = 2 time.Second coll := db.Collection("test") // Explicitly create the collection on server because implicit collection creation is not allowed in // transactions for server versions <= 4.2. err := db.RunCommand(bgCtx, bson.D{{"create", coll.Name()}}).Err() assert.Nil(t, err, "error creating collection on server: %v", err) defer func() { _ = coll.Drop(bgCtx) }() // Set failpoint to block insertOne once for 500ms. failpoint := bson.D{{"configureFailPoint", "failCommand"}, {"mode", bson.D{ {"times", 1}, }}, {"data", bson.D{ {"failCommands", bson.A{"insert"}}, {"blockConnection", true}, {"blockTimeMS", 500}, }}, } err = dbAdmin.RunCommand(bgCtx, failpoint).Err() assert.Nil(t, err, "error setting failpoint: %v", err) defer func() { err = dbAdmin.RunCommand(bgCtx, bson.D{ {"configureFailPoint", "failCommand"}, {"mode", "off"}, }).Err() assert.Nil(t, err, "error turning off failpoint: %v", err) }() sess, err := client.StartSession() assert.Nil(t, err, "StartSession error: %v", err) defer sess.EndSession(context.Background()) callback := func(ctx context.Context) { _, err = sess.WithTransaction(ctx, func(ctx SessionContext) (interface{}, error) { // Set a timeout of 300ms to cause a timeout on first insertOne // and force a retry. c, cancel := context.WithTimeout(ctx, 300time.Millisecond) defer cancel() _, err := coll.InsertOne(c, bson.D{{}}) return nil, err }) assert.Nil(t, err, "WithTransaction error: %v", err) } // Assert that transaction passes within 2 seconds. assert.Soon(t, callback, 2time.Second) }) } func setupConvenientTransactions(t testing.T, extraClientOpts ...options.ClientOptions) Client { cs := integtest.ConnString(t) poolMonitor := &event.PoolMonitor{ Event: func(evt event.PoolEvent) { switch evt.Type { case event.GetSucceeded: connsCheckedOut++ case event.ConnectionReturned: connsCheckedOut-- } }, } baseClientOpts := options.Client(). ApplyURI(cs.Original). SetReadPreference(readpref.Primary()). SetWriteConcern(writeconcern.New(writeconcern.WMajority())). SetPoolMonitor(poolMonitor) integtest.AddTestServerAPIVersion(baseClientOpts) fullClientOpts := []options.ClientOptions{baseClientOpts} fullClientOpts = append(fullClientOpts, extraClientOpts...) client, err := Connect(bgCtx, fullClientOpts...) assert.Nil(t, err, "Connect error: %v", err) version, err := getServerVersion(client.Database("admin")) assert.Nil(t, err, "getServerVersion error: %v", err) topoKind := client.deployment.(topology.Topology).Kind() if compareVersions(version, "4.1") < 0 \|\| topoKind == description.Single { t.Skip("skipping standalones and versions < 4.1") } if topoKind != description.Sharded { return client } // For sharded clusters, disconnect the previous Client and create a new one that's pinned to a single mongos. _ = client.Disconnect(bgCtx) fullClientOpts = append(fullClientOpts, options.Client().SetHosts([]string{cs.Hosts[0]})) client, err = Connect(bgCtx, fullClientOpts...) assert.Nil(t, err, "Connect error: %v", err) return client } func getServerVersion(db *Database) (string, error) { serverStatus, err := db.RunCommand( context.Background(), bson.D{{"serverStatus", 1}}, ).Raw() if err != nil { return "", err } version, err := serverStatus.LookupErr("version") if err != nil { return "", err } return version.StringValue(), nil } // compareVersions compares two version number strings (i.e. positive integers separated by // periods). Comparisons are done to the lesser precision of the two versions. For example, 3.2 is // considered equal to 3.2.11, whereas 3.2.0 is considered less than 3.2.11. // // Returns a positive int if version1 is greater than version2, a negative int if version1 is less // than version2, and 0 if version1 is equal to version2. func compareVersions(v1 string, v2 string) int { n1 := strings.Split(v1, ".") n2 := strings.Split(v2, ".") for i := 0; i < int(math.Min(float64(len(n1)), float64(len(n2)))); i++ { i1, err := strconv.Atoi(n1[i]) if err != nil { return 1 } i2, err := strconv.Atoi(n2[i]) if err != nil { return -1 } difference := i1 - i2 if difference != 0 { return difference } } return 0 }	23.26 KB	2025-05-25 12:27
📁 writeconcern	-	2025-05-25 12:27

Edit File:

Terminal