mongodocstore

Documentation

Overview

Package mongodocstore provides a docstore implementation for MongoDB and MongoDB-compatible services hosted on-premise or by cloud providers, including Amazon DocumentDB and Azure Cosmos DB.

URLs

For docstore.OpenCollection, mongodocstore registers for the scheme "mongo". The default URL opener will dial a Mongo server using the environment variable "MONGO_SERVER_URL". To customize the URL opener, or for more details on the URL format, see URLOpener. See https://gocloud.dev/concepts/urls/ for background information.

Action Lists

mongodocstore uses the unordered BulkWrite call of the underlying driver for writes, and uses Find with a list of document IDs for Get. (These implementation choices are subject to change.) It calls the BeforeDo function once before each call to the underlying driver. The as function passed to the BeforeDo function exposes the following types:

• Gets: *options.FindOptions
• writes: []mongo.WriteModel and *options.BulkWriteOptions

As

mongodocstore exposes the following types for As:

• Collection: *mongo.Collection
• Query.BeforeQuery: *options.FindOptions or bson.D (the filter for Delete and Update queries)
• DocumentIterator: *mongo.Cursor
• Error: mongo.CommandError, mongo.BulkWriteError, mongo.BulkWriteException

Special Considerations

MongoDB represents times to millisecond precision, while Go's time.Time type has nanosecond precision. To save time.Times to MongoDB without loss of precision, save the result of calling UnixNano on the time.

The official Go driver for MongoDB, go.mongodb.org/mongo-driver/mongo, lowercases struct field names; other docstore drivers do not. This means that you have to choose between interoperating with the MongoDB driver and interoperating with other docstore drivers. See Options.LowercaseFields for more information.

Example (OpenCollectionFromURL)

package main

import (
	"context"
	"log"

	"gocloud.dev/docstore"
)

func main() {
	// PRAGMA: This example is used on gocloud.dev; PRAGMA comments adjust how it is shown and can be ignored.
	// PRAGMA: On gocloud.dev, add a blank import: _ "gocloud.dev/docstore/mongodocstore"
	// PRAGMA: On gocloud.dev, hide lines until the next blank line.
	ctx := context.Background()

	// docstore.OpenCollection creates a *docstore.Collection from a URL.
	coll, err := docstore.OpenCollection(ctx, "mongo://my-db/my-collection?id_field=userID")
	if err != nil {
		log.Fatal(err)
	}
	defer coll.Close()
}

Index

• Constants
• Variables
• func Dial(ctx context.Context, uri string) (*mongo.Client, error)
• func OpenCollection(mcoll *mongo.Collection, idField string, opts *Options) (*docstore.Collection, error)
• func OpenCollectionWithIDFunc(mcoll *mongo.Collection, idFunc func(docstore.Document) interface{}, ...) (*docstore.Collection, error)
• type Options
• type URLOpener
  • func (o *URLOpener) OpenCollectionURL(ctx context.Context, u *url.URL) (*docstore.Collection, error)

Examples

• Package (OpenCollectionFromURL)
• OpenCollection
• OpenCollectionWithIDFunc

Constants

const Scheme = "mongo"

Scheme is the URL scheme mongodocstore registers its URLOpener under on docstore.DefaultMux.

Variables

var Set = wire.NewSet(
	Dial,
	wire.Struct(new(URLOpener), "Client"),
)

Set holds Wire providers for this package.

Functions

func Dial

func Dial(ctx context.Context, uri string) (*mongo.Client, error)

Dial returns a new mongoDB client that is connected to the server URI.

func OpenCollection

func OpenCollection(mcoll *mongo.Collection, idField string, opts *Options) (*docstore.Collection, error)

OpenCollection opens a MongoDB collection for use with Docstore. The idField argument is the name of the document field to use for the document ID (MongoDB's _id field). If it is empty, the field "_id" will be used.

Example

package main

import (
	"context"
	"log"

	"gocloud.dev/docstore/mongodocstore"
)

func main() {
	// PRAGMA: This example is used on gocloud.dev; PRAGMA comments adjust how it is shown and can be ignored.
	// PRAGMA: On gocloud.dev, hide lines until the next blank line.
	ctx := context.Background()

	client, err := mongodocstore.Dial(ctx, "mongodb://my-host")
	if err != nil {
		log.Fatal(err)
	}
	mcoll := client.Database("my-db").Collection("my-coll")
	coll, err := mongodocstore.OpenCollection(mcoll, "userID", nil)
	if err != nil {
		log.Fatal(err)
	}
	defer coll.Close()
}

func OpenCollectionWithIDFunc

func OpenCollectionWithIDFunc(mcoll *mongo.Collection, idFunc func(docstore.Document) interface{}, opts *Options) (*docstore.Collection, error)

OpenCollectionWithIDFunc opens a MongoDB collection for use with Docstore. The idFunc argument is function that accepts a document and returns the value to be used for the document ID (MongoDB's _id field). IDFunc should return nil if the document is missing the information to construct an ID. This will cause all actions, even Create, to fail.

Example

package main

import (
	"context"
	"log"

	"gocloud.dev/docstore"
	"gocloud.dev/docstore/mongodocstore"
)

func main() {
	// PRAGMA: This example is used on gocloud.dev; PRAGMA comments adjust how it is shown and can be ignored.
	// PRAGMA: On gocloud.dev, hide lines until the next blank line.
	ctx := context.Background()
	type HighScore struct {
		Game   string
		Player string
	}

	client, err := mongodocstore.Dial(ctx, "mongodb://my-host")
	if err != nil {
		log.Fatal(err)
	}
	mcoll := client.Database("my-db").Collection("my-coll")

	// The name of a document is constructed from the Game and Player fields.
	nameFromDocument := func(doc docstore.Document) interface{} {
		hs := doc.(*HighScore)
		return hs.Game + "|" + hs.Player
	}

	coll, err := mongodocstore.OpenCollectionWithIDFunc(mcoll, nameFromDocument, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer coll.Close()
}

Types

type Options

type Options struct {
	// Lowercase all field names for document encoding, field selection, update
	// modifications and queries.
	//
	// If false (the default), then struct fields and MongoDB document fields will
	// have the same names. For example, a struct field F will correspond to a
	// MongoDB document field "F". This setting matches the behavior of other
	// docstore drivers, making code portable across services.
	//
	// If true, all fields correspond to lower-cased MongoDB document fields. The
	// field name F will correspond to the MongoDB document field "f", for
	// instance. Use this to make code that uses this package interoperate with
	// code that uses the official Go client for MongoDB,
	// go.mongodb.org/mongo-driver/mongo, which lowercases field names.
	LowercaseFields bool
	// The name of the field holding the document revision.
	// Defaults to docstore.DefaultRevisionField.
	RevisionField string
	// Whether Query.Update writes a new revision into the updated documents.
	// The default is false, meaning that a revision will be written to all
	// documents that satisfy the query's conditions. Set to true if and only if
	// the collection's documents do not have revision fields.
	NoWriteQueryUpdateRevisions bool
}

Options holds various options.

type URLOpener

type URLOpener struct {
	// A Client is a MongoDB client that performs operations on the db, must be
	// non-nil.
	Client *mongo.Client

	// Options specifies the options to pass to OpenCollection.
	Options Options
}

URLOpener opens URLs like "mongo://mydb/mycollection". See https://docs.mongodb.com/manual/reference/limits/#naming-restrictions for naming restrictions.

The URL Host is used as the database name. The URL Path is used as the collection name.

The following query parameters are supported:

• id_field (optional): the field name to use for the "_id" field.

func (*URLOpener) OpenCollectionURL

func (o *URLOpener) OpenCollectionURL(ctx context.Context, u *url.URL) (*docstore.Collection, error)

OpenCollectionURL opens the Collection URL.