mongo-driver – go.mongodb.org/mongo-driver/mongo/writeconcern Index | Examples | Files

package writeconcern

import "go.mongodb.org/mongo-driver/mongo/writeconcern"

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.

Code:play  

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)
	}
}
Example (W2Journaled)

Configure a Client with a write concern that requests acknowledgement that exactly 2 nodes have committed and journaled write operations.

Code:play  

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
}

Index

Examples

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 

func AckWrite(wc *WriteConcern) bool

AckWrite returns true if a write concern represents an acknowledged write

Deprecated: Use WriteConcern.Acknowledged instead.

func AcknowledgedValue 

func AcknowledgedValue(rawv bson.RawValue) bool

AcknowledgedValue returns true if a BSON RawValue for a write concern represents an acknowledged write concern. The element's value must be a document representing a write concern.

Deprecated: AcknowledgedValue will not be supported in Go Driver 2.0.

Types

type Option 

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 

func J(j bool) Option

J requests acknowledgement from MongoDB that write operations are written to the journal.

Deprecated: Use the Journaled function or define a struct literal instead. For example: 

writeconcern.Journaled()

or 

journal := true
&writeconcern.WriteConcern{
	W:       2,
	Journal: &journal,
}

func W 

func W(w int) Option

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 WMajority 

func WMajority() Option

WMajority requests acknowledgement that write operations propagate to the majority of mongod instances.

Deprecated: Use Majority instead.

func WTagSet 

func WTagSet(tag string) Option

WTagSet requests acknowledgement that write operations propagate to the specified mongod instance.

Deprecated: Use Custom instead.

func WTimeout 

func WTimeout(d time.Duration) Option

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 

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 

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 

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 

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 

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 

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 

func (wc *WriteConcern) GetJ() bool

GetJ returns the write concern journaling level.

Deprecated: Use the WriteConcern.Journal field instead.

func (*WriteConcern) GetW 

func (wc *WriteConcern) GetW() interface{}

GetW returns the write concern w level.

Deprecated: Use the WriteConcern.W field instead.

func (*WriteConcern) GetWTimeout 

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 

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 

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,
}

Source Files

writeconcern.go

Version
v1.17.3 (latest)
Published
Feb 25, 2025
Platform
linux/amd64
Imports
6 packages
Last checked
12 hours ago –

Tools for package owners.