writeconcern

package
v1.17.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 1, 2024 License: Apache-2.0 Imports: 6 Imported by: 665

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

Examples

Constants

This section is empty.

Variables

View Source 
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.

View Source 
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.

View Source 
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.

View Source 
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 

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 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 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 deprecated 

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 deprecated 

func WMajority() Option

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

Deprecated: Use Majority instead.

func WTagSet deprecated 

func WTagSet(tag string) Option

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

Deprecated: Use Custom instead.

func WTimeout deprecated 

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.