What's New

What's New in 2.0

The 2.0 Go driver release supports various new features, provides a smoother timeout experience, and implements clearer, more idiomatic Go code by streamlining APIs, improving errors descriptions, and simplifying the driver package structure.

In this section, you can learn more about these changes.

This release includes the following improvements and fixes:

• You can access the GridFS API from the mongo package. In previous versions, you could access GridFS functions from the separate gridfs package, but this functionality is now merged with the main driver mongo package. To learn more, see the GridFS guide.

• The Comment field in any options struct takes a value of type any instead of type string. To set this field, you can use the SetComment() method and pass a parameter of type any.

• Updates to monitoring event documents:

  • The CommandStartedEvent and CommandFinishedEvent structs have a single ServerConnectionID field of type int64 to capture the connection ID.

  • The ConnectionID field of the PoolEvent struct takes a value of type int64 instead of uint64.

  To view sample event documents, see the Monitoring guides.

• The Session interface is converted to a struct. See the Transactions guide to learn more.

• The Distinct() method returns a struct that can be decoded into a specified type. See the Retrieve Distinct Values guide to learn more.

• The IndexView.DropOne() method returns only an error, if present. In previous versions, this method also returned the server response, which contained the number of dropped indexes. See the Remove an Index section of the Indexes guide to learn more.

• Updates to the builder pattern for types in the options package. The pattern maintains a slice of setter functions, so you cannot set data directly to an options object. This update does not generally change how you create and use options. To learn more, see the feature JIRA ticket.

• The driver no longer supports the mongo.ErrUnacknowledgedWrite sentinel error if a write operation is not acknowledged. To confirm that the server acknowledged a write operation, you must access the Acknowledged property from the result struct returned by the write method.

  The following example shows how to confirm acknowledgment of an insert operation:

  res, err := coll.InsertOne(context.TODO(), bson.D{{"x", 2}})
  if err != nil {
     panic(err)
  }
  fmt.Print(res.Acknowledged)

• You can set options for transactions run in a given session by creating a TransactionOptions instance and passing the instance to the SetDefaultTransactionOptions() method of the SessionOptions type. To learn more, see the Session and Transaction Options section of the Transactions guide.

• The Collection.Clone() method does not return an error.

What's New in 1.16

The 1.16 Go driver release includes the following improvements and fixes:

• Adds support for specifying an index type when creating an Atlas Search index.

• Reduces memory usage when the zstd compression algorithm is enabled.

• Upgrades some dependency requirements. For a list of upgrades, see the "Upgrade Dependencies" section of the v1.16 release notes.

For more information about these changes, see the v1.16 release notes on Github.

What's New in 1.15.1

The 1.15.1 Go driver patch release includes the following improvements and fixes:

• Fixes a possible connection leak where disconnecting from a replica set cluster left behind rttMonitor connections.

• Adds support for manually specifying a maxTimeMS value for read and aggregation operations when a client-wide timeout and an operation timeout are set.

• Adds a RemainingBatchLength() method that you can call on a change stream.

For more information about these changes, see the v1.15.1 release notes on Github.

What's New in 1.15

The 1.15 Go driver release includes the following improvements and fixes:

• Connection churn can be mitigated by setting a client-wide timeout by specifying the timeoutMS connection option or by calling the SetTimeout() function. When the timeout is set, the driver attempts to reuse a connection after an operation times out and waits for up to one second to check if the connection can be reused before closing it.

• Connection pool events include a Duration field to measure the checkout duration and total amount of time it took to establish a connection.

What's New in 1.14

The 1.14 Go driver release includes the following improvements and fixes:

• Go versions before 1.18 are no longer supported.

• In case of a heartbeat timeout, in-progress operations are preemptively canceled.

• Connection strings that include the "mongodb+srv://" prefix can contain capital letters in the SRV hostname.

What's New in 1.13

The 1.13 Go driver release includes the following improvements and fixes:

• Logging for server selection and SDAM. To learn more about logging, see the Logging documentation.

• Methods on the Collection type that allow you to manage search indexes programmatically.

• The event.CommandStartedEvent and event.CommandFinishedEvent events return the DatabaseName field. This field is also included in the command-logging analogs.

• In a sharded topology, when selecting a server to retry an unsuccessful query, the driver excludes the server used for the initial attempt. Instead, if there's more than one eligible mongos instance, the driver randomly selects one. Unhealthy instances are automatically excluded from selection.

• Streaming SDAM is disabled by default on AWS Lambda and similar function-as-a-service (FaaS) platforms. You can enable monitoring by using the serverMonitoringMode URI option.

What's New in 1.12.1

The 1.12 Go driver release includes the following improvements and fixes:

• The driver unpins connections when ending a session. This prevents connections from leaking when a user runs a transaction while connected to a load balancer.

• The driver does not throw a runtime error when you unmarshal an empty bson.RawValue type with an invalid type or marshal a nil pointer of a ReadConcern instance.

• Setting options.LogComponentAll as the log component correctly results in the publication of logs against all components.

What's New in 1.12

New features of the 1.12 Go driver release include:

bsonOpts := &options.BSONOptions{
     UseJSONStructTags: true,
     NilMapAsEmpty:     true,
     NilSliceAsEmpty:   true,
}
options.Client().SetBSONOptions(bsonOpts)

What's New in 1.11

New features of the 1.11 Go driver release include:

• Removal of support for MongoDB versions 3.5 and older.

• Removal of support for Go versions 1.12 and older.

• Improvements to Timeout API and behavior, including:

  • Modified retry logic for greater application resiliency.

  • Extended mongo.IsTimeout error helper to catch more timeout errors.

  • New GridFS methods that take contexts instead of using SetReadDeadline and SetWriteDeadline.

• Reduced memory allocations during operation execution.

• Fix for SRV polling bug that prevented changes in SRV records when the associated MongoDB connection string included a username and password.

• Support for GCP service accounts when using Google Cloud Key Management Services.

• Improvements to server-side resource cleanup when using the Cursor.All and Session.WithTransaction functions.

• SERVICE_HOST Kerberos authentication parameter specification enabled with the authMechanismProperties connection string option.

• Corrected output from the bson.Raw.String() method to Extended JSON type for timestamps when the BSON document contains a UTC Timestamp field.

• Resolution of conflicts when retrying reads with read concern "available" or "linearizable".

What's New in 1.10

New features of the 1.10 Go driver release include:

• Full compatibility with MongoDB 6.0.

• Support for new features related to Queryable Encryption, including new options for automatic and manual encryption.

• Support for the new Automatic Encryption Shared Library, which replaces the mongocryptd process. The shared library requires MongoDB v6.0 Enterprise or later and libmongocrypt 1.5.0 or later.

• clustered index creation support.

• A new API and ClientEncryption entity operations for encryption key management.

• A Timeout client option to set default context timeouts for each operation sent through that client.

• A patch to default data to either primitive.M or primitive.D when decoding empty types.

• Support for encoding atypical map key types for data that can be unmarshalled into a textual representation of itself.

• Performance optimizations, including:

  • Improved full document requests for before and after updates in change stream events.

  • Improved PRN and UUID generation.

  • Reduced memory consumption when compressing wire messages.

• Troubleshooting support for frequently encountered issues.

What's New in 1.9

New features of the 1.9 Go driver release include:

• Improved connection storm mitigation.

• Custom options to change-stream and aggregate operations.

• Let option on most CRUD commands that specifies parameters for use in an aggregate expression. Let must be a document that maps parameter names to values that are constant or closed expressions without references to document fields. MongoDB v5.0 or later is required.

• New constructor functions that create Cursor and SingleResult instances from marshallable and non-nil BSON documents.

What's New in 1.8

New features of the 1.8 Go driver release include:

• Full compatibility with MongoDB 5.1.

• Support for KMIP as a KMS provider for CSFLE.

• Redesigned driver connection pool for low operation Context timeouts and to reduce connection churn. Behavior changes include:

  • New connection creation times out at connectTimeoutMS.

  • At most, two new connections can be established at the same time.

• Removal of oppressive and unnecessarily gendered language in the Go driver documentation, code, tests, and spec tests.

What's New in 1.7

New features of the 1.7 Go driver release include:

• Full compatibility with MongoDB 5.0.

• Support for the "snapshot" read concern outside of multi-document transactions for certain read operations.

• Improved WriteException and BulkWriteException error messages for schema validation reported by the WriteError.Details field.

What's New in 1.6

New features of the 1.6 Go driver release include:

• Support for the MongoDB Stable API. For more information, see the Stable API Guide.

• Support for connections to any MongoDB service that runs behind a load balancer.

• Support for creating time series collections. For more information, see the Time Series Collections Guide.

• Let option for aggregate expressions.

What's New in 1.5

New features of the 1.5 Go driver release include:

• Support for Azure and GCP key-management services with Client-side Field Level Encryption.

• New errors API to detect duplicate-key errors, timeouts, and network errors.

• Server monitoring to monitor changes on a MongoDB deployment.

• Errors to prevent unexpected behavior on maps that contain multiple keys being used as a hint option, as a sort option, or for index creation.

What's New in 1.4

New features of the 1.4 Go driver release include:

• Full compatibility with MongoDB 4.4.

• Support for stapled and non-stapled OCSP verification.

• New tlsDisableOCSPEndpointCheck=true URI option to disable sending HTTP requests if the OCSP responder is not reachable from the driver and there is no stapled response.

• Additional context to errors encountered during BSON unmarshalling.

• Proper Unwrap functions for various driver error types.

What's New in 1.3

New features of the 1.3 Go driver release include:

• mgocompat package that exports a BSON registry compatible with globalsign/mgo/bson, which can be used by calling the ClientOptions.SetRegistry method.

• RegisterTypeEncoder and RegisterHookEncoder methods, which replace the deprecated RegisterEncoder method. A corresponding change has been made to replace RegisterDecoder.

What's New in 1.2

New features of the 1.2 Go driver release include:

• Support for CSFLE.

• bson.MarshalValue function, which marshals Go types to BSON.

• StringCodec, which allows non-string fields to be decoded into a String field in a struct.

• IntCodec, UIntCodec, BoolCodec, and FloatCodec added to mgocompat to allow codecs to convert between numbers and booleans.

What's New in 1.1

New features of the 1.1 Go driver release include:

• Full compatibility with MongoDB 4.2.

• Redesigned lower-level driver implementation to improve maintainability and performance.

• Connection Monitoring and Pooling specifications to monitor various connection and connection pool events with improved efficiency.

What's New in 1.0

This release adds no new features.