What's New

What's New in 2.0

The 2.0 Go driver release supports OpenID Connect (OIDC) authentication, provides a smoother client-side operations timeout (CSOT) experience, and implements clearer, more idiomatic Go code by streamlining APIs, improving errors descriptions, and simplifying the driver package structure.

You can learn more about these changes in this section, or by viewing the v2.0 Migration Guide in the Go driver source code on GitHub.

This release includes the following improvements and fixes:

• Support for OpenID Connect (OIDC) authentication. To learn more, see the MONGODB-OIDC section of the Enterprise Authentication Mechanisms guide.

• 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.

• Renames the canonical parameter of the UnmarshalExtJSON() method to canonicalOnly. If you set canonicalOnly to true, the method returns an error if the extended JSON is not marshaled in canonical mode. If set to false, the method can unmarshal canonical or relaxed extended JSON. To learn more, see the UnmarshalExtJSON() API documentation.

What's New in 1.17

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

• Adds support for OpenID Connect (OIDC) authentication. To learn more, see the MONGODB-OIDC section of the Enterprise Authentication Mechanisms guide.

• Adds support for Queryable Encryption (QE) range queries. To use this feature, your app must connect to MongoDB Server 8.0 or later. For more information about QE range queries, see Queryable Encryption in the MongoDB Server manual.

• Adds support for MongoDB Server 8.0, except for the client bulk write feature.

• Extends the IndexView type to include the DropOneWithKey() and DropWithKey() methods so you can drop indexes by using their key specifications instead of their names.

For more information about the changes in this version, see the v1.17 release notes on GitHub.

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)