[GODRIVER-2685] Simplify "writeconcern" API Created: 11/Dec/22  Updated: 28/Oct/23  Resolved: 14/Jun/23

Status: Closed
Project: Go Driver
Component/s: None
Affects Version/s: None
Fix Version/s: 1.12.0

Type: Improvement Priority: Unknown
Reporter: Matt Dale Assignee: Matt Dale
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Depends
is depended on by GODRIVER-2696 Allow only 0 or 1 options structs in ... Investigating
Documented
Duplicate
is duplicated by GODRIVER-1179 Reference to "WTagSet" when configuri... Closed
Related
related to GODRIVER-2953 Make setting journaled=true on a writ... Backlog
related to GODRIVER-2812 Make "WriteConcern" struct parameteri... Closed
is related to GODRIVER-964 make option type construction consist... Closed
Epic Link: Go Driver 2.0 Prep
Quarter: FY24Q1
Documentation Changes: Needed
Documentation Changes Summary:

1. What would you like to communicate to the user about this feature?
There is a new standard syntax for defining write concerns in the Go driver.

2. Would you like the user to see examples of the syntax and/or executable code and its output?
Yes. All examples showing how to specify a write concern should be updated to use the new syntax.

At least the following pages contain examples that should be updated:

3. Which versions of the driver/connector does this apply to?
v1.12+


 Description   

The writeconcern package and types use a lot of unnecessary APIs that can confuse users. Additionally, there is no shortcut for specifying common write concerns like there is for the readconcern and readpref packages. We should remove the functional options pattern and just export all fields in the WriteConcern struct so users can set them directly. We should add package functions for quickly specifying common write concerns "majority", "w: 0", and "w: 1".

Also, some exported values or functions do not need to be exported:

  • ErrInconsistent, ErrEmptyWriteConcern, ErrNegativeW, ErrNegativeWTimeout - Unless users are dynamically building write concerns at application time, these error are unrecoverable and do not need to support special conditional logic (i.e. if err == ErrInconsistent).
  • WriteConcern.MarshalBSONValue - The single known use case outside of the Go driver is in mongorestore, which uses it to make a copy of a write concern. That use case is removed by exporting the write concern fields.

Definition of done:

  • Add package functions for creating common write concerns
    • Majority
    • W0
    • W1
    • Custom(tag string)
  • Export all fields in the WriteConcern struct and add documentation for what each field does and what values are valid.
    • When exporting the J field, change it to type *bool so we can represent either true, false or unset. Also update the logic to only exclude J from the marshaled document if it's unset, but always include explicit true or false.
  • Deprecate Option type and all Option functions.
  • Deprecate New.
  • Deprecate all error values.
  • Deprecate WriteConcern.MarshalBSONValue

Note that all deprecated code will be removed or unexported in Go Driver 2.0.



 Comments   
Comment by Githook User [ 14/Jun/23 ]

Author:

{'name': 'Matt Dale', 'email': '9760375+matthewdale@users.noreply.github.com', 'username': 'matthewdale'}

Message: GODRIVER-2685 Simplify the writeconcern API. (#1232)
Branch: master
https://github.com/mongodb/mongo-go-driver/commit/a10150b0070a7882af25a7946cf8cd438ed0e3ef

Comment by Matt Dale [ 18/Apr/23 ]

PR: https://github.com/mongodb/mongo-go-driver/pull/1232

Generated at Thu Feb 08 08:39:09 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.