Documentation ¶
Overview ¶
Package writeconcern defines write concerns for MongoDB operations.
For more information about MongoDB write concerns, see https://www.mongodb.com/docs/manual/reference/write-concern/
Example (Majority) ¶
Configure a Client with write concern "majority" that requests acknowledgement that a majority of the nodes have committed write operations.
package main import ( "context" "go.mongodb.org/mongo-driver/mongo" "go.mongodb.org/mongo-driver/mongo/options" "go.mongodb.org/mongo-driver/mongo/writeconcern" ) func main() { wc := writeconcern.Majority() opts := options.Client(). ApplyURI("mongodb://localhost:27017"). SetWriteConcern(wc) _, err := mongo.Connect(context.Background(), opts) if err != nil { panic(err) } }
Output:
Example (W2Journaled) ¶
Configure a Client with a write concern that requests acknowledgement that exactly 2 nodes have committed and journaled write operations.
package main import ( "context" "go.mongodb.org/mongo-driver/mongo" "go.mongodb.org/mongo-driver/mongo/options" "go.mongodb.org/mongo-driver/mongo/writeconcern" ) func main() { wc := &writeconcern.WriteConcern{ W: 2, Journal: boolPtr(true), } opts := options.Client(). ApplyURI("mongodb://localhost:27017"). SetWriteConcern(wc) _, err := mongo.Connect(context.Background(), opts) if err != nil { panic(err) } } // boolPtr is a helper function to convert a bool constant into a bool pointer. // // If you're using a version of Go that supports generics, you can define a // generic version of this function that works with any type. For example: // // func ptr[T any](v T) *T { // return &v // } func boolPtr(b bool) *bool { return &b }
Output:
Index ¶
- Variables
- func AckWrite(wc *WriteConcern) booldeprecated
- func AcknowledgedValue(rawv bson.RawValue) booldeprecated
- type Optiondeprecated
- func J(j bool) Optiondeprecated
- func W(w int) Optiondeprecated
- func WMajority() Optiondeprecated
- func WTagSet(tag string) Optiondeprecated
- func WTimeout(d time.Duration) Optiondeprecated
- type WriteConcern
- func (wc *WriteConcern) Acknowledged() bool
- func (wc *WriteConcern) GetJ() booldeprecated
- func (wc *WriteConcern) GetW() interface{}deprecated
- func (wc *WriteConcern) GetWTimeout() time.Durationdeprecated
- func (wc *WriteConcern) IsValid() bool
- func (wc *WriteConcern) MarshalBSONValue() (bsontype.Type, []byte, error)deprecated
- func (wc *WriteConcern) WithOptions(options ...Option) *WriteConcerndeprecated
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrEmptyWriteConcern = errors.New("a write concern must have at least one field set")
ErrEmptyWriteConcern indicates that a write concern has no fields set.
Deprecated: ErrEmptyWriteConcern will be removed in Go Driver 2.0.
var ErrInconsistent = errors.New("a write concern cannot have both w=0 and j=true")
ErrInconsistent indicates that an inconsistent write concern was specified.
Deprecated: ErrInconsistent will be removed in Go Driver 2.0.
var ErrNegativeW = errors.New("write concern `w` field cannot be a negative number")
ErrNegativeW indicates that a negative integer `w` field was specified.
Deprecated: ErrNegativeW will be removed in Go Driver 2.0.
var ErrNegativeWTimeout = errors.New("write concern `wtimeout` field cannot be negative")
ErrNegativeWTimeout indicates that a negative WTimeout was specified.
Deprecated: ErrNegativeWTimeout will be removed in Go Driver 2.0.
Functions ¶
func AckWrite
deprecated
added in
v0.0.18
func AckWrite(wc *WriteConcern) bool
AckWrite returns true if a write concern represents an acknowledged write
Deprecated: Use WriteConcern.Acknowledged instead.
func AcknowledgedValue
deprecated
added in
v0.2.0
Types ¶
type Option
deprecated
type Option func(concern *WriteConcern)
Option is an option to provide when creating a WriteConcern.
Deprecated: Use the WriteConcern convenience functions or define a struct literal instead. For example:
writeconcern.Majority()
or
journal := true &writeconcern.WriteConcern{ W: 2, Journal: &journal, }
func J
deprecated
func W
deprecated
W requests acknowledgement that write operations propagate to the specified number of mongod instances.
Deprecated: Use the Unacknowledged or W1 functions or define a struct literal instead. For example:
writeconcern.Unacknowledged()
or
journal := true &writeconcern.WriteConcern{ W: 2, Journal: &journal, }
func WTimeout
deprecated
WTimeout specifies a time limit for the write concern.
It is only applicable for "w" values greater than 1. Using a WTimeout and setting Timeout on the Client at the same time will result in undefined behavior.
Deprecated: Use the WriteConcern convenience functions or define a struct literal instead. For example:
wc := writeconcern.W1() wc.WTimeout = 30 * time.Second
or
journal := true &writeconcern.WriteConcern{ W: "majority", WTimeout: 30 * time.Second, }
type WriteConcern ¶
type WriteConcern struct { // W requests acknowledgment that the write operation has propagated to a // specified number of mongod instances or to mongod instances with // specified tags. It sets the "w" option in a MongoDB write concern. // // W values must be a string or an int. // // Common values are: // - "majority": requests acknowledgment that write operations have been // durably committed to the calculated majority of the data-bearing // voting members. // - 1: requests acknowledgment that write operations have been written // to 1 node. // - 0: requests no acknowledgment of write operations // // For more information about the "w" option, see // https://www.mongodb.com/docs/manual/reference/write-concern/#w-option W interface{} // Journal requests acknowledgment from MongoDB that the write operation has // been written to the on-disk journal. It sets the "j" option in a MongoDB // write concern. // // For more information about the "j" option, see // https://www.mongodb.com/docs/manual/reference/write-concern/#j-option Journal *bool // WTimeout specifies a time limit for the write concern. It sets the // "wtimeout" option in a MongoDB write concern. // // It is only applicable for "w" values greater than 1. Using a WTimeout and // setting Timeout on the Client at the same time will result in undefined // behavior. // // For more information about the "wtimeout" option, see // https://www.mongodb.com/docs/manual/reference/write-concern/#wtimeout WTimeout time.Duration }
A WriteConcern defines a MongoDB write concern, which describes the level of acknowledgment requested from MongoDB for write operations to a standalone mongod, to replica sets, or to sharded clusters.
For more information about MongoDB write concerns, see https://www.mongodb.com/docs/manual/reference/write-concern/
func Custom ¶ added in v1.12.0
func Custom(tag string) *WriteConcern
Custom returns a WriteConcern that requests acknowledgment that write operations have propagated to tagged members that satisfy the custom write concern defined in "settings.getLastErrorModes".
For more information about custom write concern names, see https://www.mongodb.com/docs/manual/reference/write-concern/#mongodb-writeconcern-writeconcern.-custom-write-concern-name-
func Journaled ¶ added in v1.12.0
func Journaled() *WriteConcern
Journaled returns a WriteConcern that requests acknowledgment that write operations have been written to the on-disk journal on MongoDB.
The database's default value for "w" determines how many nodes must write to their on-disk journal before the write operation is acknowledged.
For more information about write concern "j: true", see https://www.mongodb.com/docs/manual/reference/write-concern/#mongodb-writeconcern-ournal
func Majority ¶ added in v1.12.0
func Majority() *WriteConcern
Majority returns a WriteConcern that requests acknowledgment that write operations have been durably committed to the calculated majority of the data-bearing voting members.
Write concern "w: majority" typically requires write operations to be written to the on-disk journal before they are acknowledged, unless journaling is disabled on MongoDB or the "writeConcernMajorityJournalDefault" replica set configuration is set to false.
For more information about write concern "w: majority", see https://www.mongodb.com/docs/manual/reference/write-concern/#mongodb-writeconcern-writeconcern.-majority-
func New
deprecated
func New(options ...Option) *WriteConcern
New constructs a new WriteConcern.
Deprecated: Use the WriteConcern convenience functions or define a struct literal instead. For example:
writeconcern.Majority()
or
journal := true &writeconcern.WriteConcern{ W: 2, Journal: &journal, }
func Unacknowledged ¶ added in v1.12.0
func Unacknowledged() *WriteConcern
Unacknowledged returns a WriteConcern that requests no acknowledgment of write operations.
For more information about write concern "w: 0", see https://www.mongodb.com/docs/manual/reference/write-concern/#mongodb-writeconcern-writeconcern.-number-
func W1 ¶ added in v1.12.0
func W1() *WriteConcern
W1 returns a WriteConcern that requests acknowledgment that write operations have been written to memory on one node (e.g. the standalone mongod or the primary in a replica set).
For more information about write concern "w: 1", see https://www.mongodb.com/docs/manual/reference/write-concern/#mongodb-writeconcern-writeconcern.-number-
func (*WriteConcern) Acknowledged ¶
func (wc *WriteConcern) Acknowledged() bool
Acknowledged indicates whether or not a write with the given write concern will be acknowledged.
func (*WriteConcern) GetJ
deprecated
added in
v1.0.0
func (wc *WriteConcern) GetJ() bool
GetJ returns the write concern journaling level.
Deprecated: Use the WriteConcern.Journal field instead.
func (*WriteConcern) GetW
deprecated
added in
v1.0.0
func (wc *WriteConcern) GetW() interface{}
GetW returns the write concern w level.
Deprecated: Use the WriteConcern.W field instead.
func (*WriteConcern) GetWTimeout
deprecated
added in
v1.0.0
func (wc *WriteConcern) GetWTimeout() time.Duration
GetWTimeout returns the write concern timeout.
Deprecated: Use the WriteConcern.WTimeout field instead.
func (*WriteConcern) IsValid ¶
func (wc *WriteConcern) IsValid() bool
IsValid returns true if the WriteConcern is valid.
func (*WriteConcern) MarshalBSONValue
deprecated
added in
v0.2.0
func (wc *WriteConcern) MarshalBSONValue() (bsontype.Type, []byte, error)
MarshalBSONValue implements the bson.ValueMarshaler interface.
Deprecated: Marshaling a WriteConcern to BSON will not be supported in Go Driver 2.0.
func (*WriteConcern) WithOptions
deprecated
added in
v1.0.0
func (wc *WriteConcern) WithOptions(options ...Option) *WriteConcern
WithOptions returns a copy of this WriteConcern with the options set.
Deprecated: Use the WriteConcern convenience functions or define a struct literal instead. For example:
writeconcern.Majority()
or
journal := true &writeconcern.WriteConcern{ W: 2, Journal: &journal, }