mongodb

package
v3.8.0 Latest Latest
Warning

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

 Go to latest Published: Oct 30, 2024 License: MIT Imports: 20 Imported by: 35

README

Mongo Driver

This library is intended to be an abstraction that can encapsulate the mongo db and the document db operations. All functionality that accesses the db is intended to be accessed via this library. The library is responsible for connection handling as well as querying.

Documentation

Index

Examples

Constants

View Source 
const (
	LastUpdatedKey     = "last_updated"
	UniqueTimestampKey = "unique_timestamp"
)

keep these in sync with Timestamps tags below

Variables

View Source 
var (
	NoCACertChain      = errors.New("no CA certificate chain supplied, or chain cannot be read")
	InvalidCACertChain = errors.New("cannot parse CA certificate chain - invalid or corrupt")
)
View Source 
var (
	ErrDisconnect      = mongo.ErrClientDisconnected
	ErrNoDocumentFound = mongo.ErrNoDocuments
)
View Source 
var (
	Sort   = func(s interface{}) FindOption { return func(f *findOptions) { f.sort = s } }
	Offset = func(o int) FindOption { return func(f *findOptions) { f.skip = int64(o) } }
	Limit  = func(l int) FindOption {
		return func(f *findOptions) {
			f.limit = int64(l)
			if l == 0 {
				f.obeyZeroLimit = true
			}
		}
	}
	Projection = func(p interface{}) FindOption { return func(f *findOptions) { f.projection = p } }

	IgnoreZeroLimit = func() FindOption { return func(f *findOptions) { f.obeyZeroLimit = false } }
)

Functions

func IsServerErr 

func IsServerErr(err error) bool

func IsTimeout 

func IsTimeout(err error) bool

func WithLastUpdatedUpdate 

func WithLastUpdatedUpdate(updateDoc bson.M) (bson.M, error)

WithLastUpdatedUpdate adds last_updated to updateDoc

func WithNamespacedLastUpdatedUpdate 

func WithNamespacedLastUpdatedUpdate(updateDoc bson.M, prefixes []string) (newUpdateDoc bson.M, err error)

WithNamespacedLastUpdatedUpdate adds unique timestamp to updateDoc

func WithNamespacedUniqueTimestampQuery 

func WithNamespacedUniqueTimestampQuery(queryDoc bson.M, timestamps []primitive.Timestamp, prefixes []string) bson.M

WithNamespacedUniqueTimestampQuery adds unique timestamps to queryDoc sub-docs

func WithNamespacedUniqueTimestampUpdate 

func WithNamespacedUniqueTimestampUpdate(updateDoc bson.M, prefixes []string) (newUpdateDoc bson.M, err error)

WithNamespacedUniqueTimestampUpdate adds unique timestamp to updateDoc

func WithNamespacedUpdates 

func WithNamespacedUpdates(updateDoc bson.M, prefixes []string) (bson.M, error)

WithNamespacedUpdates adds all timestamps to updateDoc

func WithUniqueTimestampQuery 

func WithUniqueTimestampQuery(queryDoc bson.M, timestamp primitive.Timestamp) bson.M

WithUniqueTimestampQuery adds unique timestamp to queryDoc

func WithUniqueTimestampUpdate 

func WithUniqueTimestampUpdate(updateDoc bson.M) (bson.M, error)

WithUniqueTimestampUpdate adds unique timestamp to updateDoc

func WithUpdates 

func WithUpdates(updateDoc bson.M) (bson.M, error)

WithUpdates adds all timestamps to updateDoc

Types

type Collection 

type Collection struct {
	// contains filtered or unexported fields
}

Collection is a handle to a MongoDB collection

func NewCollection 

func NewCollection(collection *mongo.Collection) *Collection

NewCollection creates a new collection

func (*Collection) Aggregate 

func (c *Collection) Aggregate(ctx context.Context, pipeline, results interface{}) error

Aggregate starts a pipeline operation

func (*Collection) Count 

func (c *Collection) Count(ctx context.Context, filter interface{}, opts ...FindOption) (int, error)

Count returns the number of documents in the collection that satisfy the given filter (which cannot be nil) Sort and Projection options are ignored. A Limit option <=0 is ignored, and a count of all documents is returned

func (*Collection) Delete 

func (c *Collection) Delete(ctx context.Context, selector interface{}) (*CollectionDeleteResult, error)

Delete deletes a single document based on the provided selector Deprecated: Use DeleteOne instead

func (*Collection) DeleteById 

func (c *Collection) DeleteById(ctx context.Context, id interface{}) (*CollectionDeleteResult, error)

DeleteById deletes a document based on the provided id selector Deprecated: Use DeleteOne

func (*Collection) DeleteMany 

func (c *Collection) DeleteMany(ctx context.Context, selector interface{}) (*CollectionDeleteResult, error)

DeleteMany deletes multiple documents based on the provided selector The selector must be a document containing query operators and cannot be nil. If the selector does not match any documents, the operation will succeed and a CollectionDeleteResult with a DeletedCount of 0 will be returned.

func (*Collection) DeleteOne added in v3.5.0 

func (c *Collection) DeleteOne(ctx context.Context, selector interface{}) (*CollectionDeleteResult, error)

DeleteOne deletes a single document based on the provided selector. The selector must be a document containing query operators and cannot be nil. If the selector does not match any documents, the operation will succeed and a CollectionDeleteResult with a DeletedCount of 0 will be returned. If the selector matches multiple documents, one will be selected from the matched set, deleted and a CollectionDeleteResult with a DeletedCount of 1 will be returned.

func (*Collection) Distinct 

func (c *Collection) Distinct(ctx context.Context, fieldName string, filter interface{}) ([]interface{}, error)

Distinct returns the list of distinct values for the given field name in the collection

func (*Collection) Find 

func (c *Collection) Find(ctx context.Context, filter, results interface{}, opts ...FindOption) (int, error)

Find returns the total number of documents in the collection that satisfy the given filter (restricted by the given options), with the actual documents provided in the results parameter (which must be a non nil pointer to a slice of the expected document type) If no sort order option is provided a default sort order of 'ascending _id' is used (bson.M{"_id": 1})

func (*Collection) FindCursor added in v3.1.0 

func (c *Collection) FindCursor(ctx context.Context, filter interface{}, opts ...FindOption) (Cursor, error)

FindCursor returns a mongo cursor iterating over the collection If no sort order option is provided a default sort order of 'ascending _id' is used (bson.M{"_id": 1})

func (*Collection) FindOne 

func (c *Collection) FindOne(ctx context.Context, filter interface{}, result interface{}, opts ...FindOption) error

FindOne returns a single document in the collection that satisfies the given filter (restricted by the given options), with the actual document provided in the result parameter (which must be a non nil pointer to a document of the expected type) If no document could be found, an ErrNoDocumentFound error is returned

func (*Collection) Insert 

func (c *Collection) Insert(ctx context.Context, document interface{}) (*CollectionInsertResult, error)

Insert creates a single document in the collection Deprecated: Use InsertOne

func (*Collection) InsertMany 

func (c *Collection) InsertMany(ctx context.Context, documents []interface{}) (*CollectionInsertManyResult, error)

InsertMany creates multiple documents in the collection The documents must be a slice of documents to insert and slice cannot be nil or empty. The elements must all be non-nil. For any document that does not have an _id field when transformed into BSON, one will be added automatically to the marshalled document. The _id values for the inserted documents can be retrieved from the InsertedIds field of the returned CollectionInsertManyResult.

func (*Collection) InsertOne added in v3.5.0 

func (c *Collection) InsertOne(ctx context.Context, document interface{}) (*CollectionInsertResult, error)

InsertOne creates a single document in the collection The document must be the document to be inserted and cannot be nil. If the document does not have an _id field when transformed into BSON, one will be added automatically to the marshalled document. The _id can be retrieved from the InsertedId field of the returned CollectionInsertResult.

func (*Collection) Must 

func (c *Collection) Must() *Must

Must creates a new Must for the collection

func (*Collection) NewLockClient 

func (c *Collection) NewLockClient() *lock.Client

NewLockClient creates a new Lock Client

func (*Collection) Update 

func (c *Collection) Update(ctx context.Context, selector interface{}, update interface{}) (*CollectionUpdateResult, error)

Update modifies a single document located by the provided selector Deprecated: Use UpdateOne

func (*Collection) UpdateById 

func (c *Collection) UpdateById(ctx context.Context, id interface{}, update interface{}) (*CollectionUpdateResult, error)

UpdateById modifies a single document located by the provided id selector Deprecated: Use UpdateOne

func (*Collection) UpdateMany 

func (c *Collection) UpdateMany(ctx context.Context, selector interface{}, update interface{}) (*CollectionUpdateResult, error)

UpdateMany modifies multiple documents located by the provided selector The selector must be a document containing query operators and cannot be nil. The update must be a document containing update operators and cannot be nil or empty. If the selector does not match any documents, the operation will succeed and a CollectionUpdateResult with a MatchedCount of 0 will be returned.

func (*Collection) UpdateOne added in v3.5.0 

func (c *Collection) UpdateOne(ctx context.Context, selector interface{}, update interface{}) (*CollectionUpdateResult, error)

UpdateOne modifies a single document located by the provided selector The selector must be a document containing query operators and cannot be nil. The update must be a document containing update operators and cannot be nil or empty. If the selector does not match any documents, the operation will succeed and a CollectionUpdateResult with a MatchedCount of 0 will be returned. If the selector matches multiple documents, one will be selected from the matched set, updated and a CollectionUpdateResult with a MatchedCount of 1 will be returned.

func (*Collection) Upsert 

func (c *Collection) Upsert(ctx context.Context, selector interface{}, update interface{}) (*CollectionUpdateResult, error)

Upsert creates or updates a document located by the provided selector Deprecated: Use UpsertOne

func (*Collection) UpsertById 

func (c *Collection) UpsertById(ctx context.Context, id interface{}, update interface{}) (*CollectionUpdateResult, error)

UpsertById creates or updates a document located by the provided id selector Deprecated: Use UpsertOne

func (*Collection) UpsertOne added in v3.5.0 

func (c *Collection) UpsertOne(ctx context.Context, selector interface{}, update interface{}) (*CollectionUpdateResult, error)

UpsertOne creates or updates a document located by the provided selector The selector must be a document containing query operators and cannot be nil. The update must be a document containing update operators and cannot be nil or empty. If the selector does not match any documents, the update document is inserted into the collection. If the selector matches multiple documents, one will be selected from the matched set, updated and a CollectionUpdateResult with a MatchedCount of 1 will be returned.

type CollectionDeleteResult 

type CollectionDeleteResult struct {
	DeletedCount int // The number of documents deleted
}

CollectionDeleteResult is the result type returned from Delete, DeleteById and DeleteMany operations.

type CollectionInsertManyResult 

type CollectionInsertManyResult struct {
	InsertedIds []interface{} // inserted Ids
}

CollectionInsertManyResult is the result type returned from InsertMany operations.

type CollectionInsertResult 

type CollectionInsertResult struct {
	InsertedId interface{} // Id of the document inserted
}

CollectionInsertResult is the result type return from Insert

type CollectionUpdateResult 

type CollectionUpdateResult struct {
	MatchedCount  int         // The number of documents matched by the filter.
	ModifiedCount int         // The number of documents modified by the operation.
	UpsertedCount int         // The number of documents upserted by the operation.
	UpsertedID    interface{} // The _id field of the upserted document, or nil if no upsert was done.
}

CollectionUpdateResult is the result type returned from Update, UpdateById, Upsert and UpsertById operations.

type Cursor added in v3.1.0 

type Cursor interface {
	Close(ctx context.Context) error
	Next(ctx context.Context) bool
	Decode(val interface{}) error
	Err() error
}

type Error 

type Error struct {
	// contains filtered or unexported fields
}

func (Error) Error 

func (e Error) Error() string

func (Error) Unwrap 

func (e Error) Unwrap() error

type FindOption 

type FindOption func(*findOptions)

type Graceful 

type Graceful interface {
	// contains filtered or unexported methods
}

Graceful represents an interface to the shutdown method

type MongoConnection 

type MongoConnection struct {
	// contains filtered or unexported fields
}

func NewMongoConnection 

func NewMongoConnection(client *mongo.Client, database string) *MongoConnection

func Open 

func Open(m *MongoDriverConfig) (*MongoConnection, error)
Example

Example of how to connect to a Mongo DB server with SSL, in this case a connection via ssh port forwarding to a DocumentDB server cluster: `dp ssh develop publishing 1 -p 27017:develop-docdb-cluster.cluster-cpviojtnaxsj.eu-west-1.docdb.amazonaws.com:27017` 

connectionConfig := &mongoDriver.MongoDriverConfig{
	ClusterEndpoint: "localhost:27017",
	Database:        "recipes",
	Username:        "XXX- username for recipe-api for authentication",
	Password:        "XXX - the password for the above username",

	ConnectTimeout:                5 * time.Second,
	QueryTimeout:                  5 * time.Second,
	IsStrongReadConcernEnabled:    true,
	IsWriteConcernMajorityEnabled: true,
	TLSConnectionConfig: mongoDriver.TLSConnectionConfig{
		IsSSL:              true,
		VerifyCert:         true,
		CACertChain:        "-----BEGIN CERTIFICATE-----ACTUAL CERT CONTENTS -----END CERTIFICATE-----",
		RealHostnameForSSH: "develop-docdb-cluster.cluster-cpviojtnaxsj.eu-west-1.docdb.amazonaws.com",
	},
}

mongoDB, err := mongoDriver.Open(connectionConfig)
if err != nil {
	// log error, cannot use mongo db
}

// Can now work with the mongo db
ctx, cancel := context.WithTimeout(context.Background(), 1*time.Second)
defer cancel()
_, _ = mongoDB.Collection("recipes").InsertOne(ctx, bson.M{"recipe field": "field value"})

Output:

func (*MongoConnection) Close 

func (ms *MongoConnection) Close(ctx context.Context) error

Close represents mongo session closing within the context deadline

func (*MongoConnection) Collection 

func (ms *MongoConnection) Collection(collection string) *Collection

func (*MongoConnection) DropDatabase 

func (ms *MongoConnection) DropDatabase(ctx context.Context) error

func (*MongoConnection) ListCollectionsFor 

func (ms *MongoConnection) ListCollectionsFor(ctx context.Context, database string) ([]string, error)

func (*MongoConnection) Ping 

func (ms *MongoConnection) Ping(ctx context.Context, timeoutInSeconds time.Duration) error

func (*MongoConnection) RunCommand 

func (ms *MongoConnection) RunCommand(ctx context.Context, runCommand interface{}) error

RunCommand executes the given command against the configured database. This is provided for tests only and no values are returned

func (*MongoConnection) RunTransaction added in v3.4.0 

func (ms *MongoConnection) RunTransaction(ctx context.Context, withRetries bool, fn TransactionFunc) (interface{}, error)

RunTransaction will execute the given function - fn - within a transaction, defined by the transaction context - transactionCtx If withRetries is true, the transaction will retry on a transient transaction error - this can be due to a network error, but may also occur if the state of an object being updated in the transaction has been changed since the transaction started. This latter behaviour may or may be suitable depending on the circumstances, and so is optional The return values of the function are the return values provided by the TransactionFunc fn, except in the case where runtime errors occur outside the TransactionFunc fn, when committing or aborting the transaction

type MongoConnector 

type MongoConnector interface {
	Collection(collection string) *Collection
	ListCollectionsFor(ctx context.Context, database string) ([]string, error)
	DropDatabase(ctx context.Context) error
	RunCommand(ctx context.Context, runCommand interface{}) error
	Ping(ctx context.Context, timeoutInSeconds time.Duration) error
	Close(ctx context.Context) error
}

type MongoDriverConfig 

type MongoDriverConfig struct {
	Username        string `envconfig:"MONGODB_USERNAME"    json:"-"`
	Password        string `envconfig:"MONGODB_PASSWORD"    json:"-"`
	ClusterEndpoint string `envconfig:"MONGODB_BIND_ADDR"   json:"-"`
	Database        string `envconfig:"MONGODB_DATABASE"`
	// Collections is a mapping from a collection's 'Well Known Name' to 'Actual Name'
	Collections                   map[string]string `envconfig:"MONGODB_COLLECTIONS"`
	ReplicaSet                    string            `envconfig:"MONGODB_REPLICA_SET"`
	IsStrongReadConcernEnabled    bool              `envconfig:"MONGODB_ENABLE_READ_CONCERN"`
	IsWriteConcernMajorityEnabled bool              `envconfig:"MONGODB_ENABLE_WRITE_CONCERN"`

	ConnectTimeout time.Duration `envconfig:"MONGODB_CONNECT_TIMEOUT"`
	QueryTimeout   time.Duration `envconfig:"MONGODB_QUERY_TIMEOUT"`

	TLSConnectionConfig
}

func (*MongoDriverConfig) ActualCollectionName 

func (m *MongoDriverConfig) ActualCollectionName(wellKnownName string) string

func (*MongoDriverConfig) GetConnectionURI 

func (m *MongoDriverConfig) GetConnectionURI() (string, error)

type Must 

type Must struct {
	// contains filtered or unexported fields
}

func (*Must) Delete 

func (m *Must) Delete(ctx context.Context, selector interface{}) (*CollectionDeleteResult, error)

Delete deletes a single document located by the provided selector. If no document is not found an ErrNoDocumentFound error is returned Deprecated: Use DeleteOne

func (*Must) DeleteById 

func (m *Must) DeleteById(ctx context.Context, id interface{}) (*CollectionDeleteResult, error)

DeleteById deletes a single document located by the provided id selector. If no document is not found an ErrNoDocumentFound error is returned Deprecated: Use DeleteOne

func (*Must) DeleteMany 

func (m *Must) DeleteMany(ctx context.Context, selector interface{}) (*CollectionDeleteResult, error)

DeleteMany deletes multiple documents located by the provided selector. The selector must be a document containing query operators and cannot be nil. If the selector does not match any documents, an ErrNoDocumentFound error is returned

func (*Must) DeleteOne added in v3.5.0 

func (m *Must) DeleteOne(ctx context.Context, selector interface{}) (*CollectionDeleteResult, error)

DeleteOne deletes a single document located by the provided selector. The selector must be a document containing query operators and cannot be nil. If the selector does not match any documents, an ErrNoDocumentFound error is returned If the selector matches multiple documents, one will be selected from the matched set, deleted and a CollectionDeleteResult with a DeletedCount of 1 will be returned.

func (*Must) Update 

func (m *Must) Update(ctx context.Context, selector interface{}, update interface{}) (*CollectionUpdateResult, error)

Update modifies a single document located by the provided selector. If a document cannot be found, an ErrNoDocumentFound error is returned Deprecated: Use UpdateOne instead

func (*Must) UpdateById 

func (m *Must) UpdateById(ctx context.Context, id interface{}, update interface{}) (*CollectionUpdateResult, error)

UpdateById modifies a single document located by the provided id selector. If a document cannot be found, an ErrNoDocumentFound error is returned Deprecated: Use UpdateOne instead

func (*Must) UpdateMany added in v3.5.0 

func (m *Must) UpdateMany(ctx context.Context, selector interface{}, update interface{}) (*CollectionUpdateResult, error)

UpdateMany modifies multiple documents located by the provided selector. The selector must be a document containing query operators and cannot be nil. The update must be a document containing update operators and cannot be nil or empty. If the selector does not match any documents, an ErrNoDocumentFound is returned

func (*Must) UpdateOne added in v3.5.0 

func (m *Must) UpdateOne(ctx context.Context, selector interface{}, update interface{}) (*CollectionUpdateResult, error)

UpdateOne modifies a single document located by the provided selector. The selector must be a document containing query operators and cannot be nil. The update must be a document containing update operators and cannot be nil or empty. If the selector does not match any documents, an ErrNoDocumentFound is returned If the selector matches multiple documents, one will be selected from the matched set, updated and a CollectionUpdateResult with a MatchedCount of 1 will be returned.

type TLSConnectionConfig 

type TLSConnectionConfig struct {
	IsSSL              bool   `envconfig:"MONGODB_IS_SSL"`
	VerifyCert         bool   `envconfig:"MONGODB_VERIFY_CERT"`
	CACertChain        string `envconfig:"MONGODB_CERT_CHAIN"`
	RealHostnameForSSH string `envconfig:"MONGODB_REAL_HOSTNAME"`
}

TLSConnectionConfig supplies the options for setting up a TLS based connection to the Mongo DB server If the Mongo server certificate is to be validated (a major security breach not doing so), the VerifyCert should be true, and the chain of CA certificates for the validation must be supplied If the connection to the server is being made with an IP address, or via an SSH proxy (such as with `dp ssh develop publishing 1 -p local-port:remote-host:remote-port`) the real hostname should be supplied in the RealHostnameForSSH attribute. The real hostname is the name of the server as attested by the server's x509 certificate. So in the above example of a connection via ssh this would be the value of `remotehost`

func (TLSConnectionConfig) GetTLSConfig 

func (m TLSConnectionConfig) GetTLSConfig() (*tls.Config, error)

type Timestamps 

type Timestamps struct {
	LastUpdated     time.Time            `bson:"last_updated,omitempty"     json:"last_updated,omitempty"`
	UniqueTimestamp *primitive.Timestamp `bson:"unique_timestamp,omitempty" json:"-"`
}

Timestamps represent an object containing time stamps keep these in sync with above const

type TransactionFunc added in v3.4.0 

type TransactionFunc func(transactionCtx context.Context) (interface{}, error)

TransactionFunc is the type signature of a client function that is to be executed within a transaction, defined by the transaction context provided as the parameter to the function - transactionCtx All calls to the mongodb library to be executed within the transaction must be passed the transactionCtx Returning an error from the function indicates the transaction is to be aborted

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.