mongodialect

README

mongodialect

Wrapper for generic access to a MongoDB database. Supports finding, inserting, updating and deleting documents from collections.

Documentation

Index

• Variables
• func NewDatabaseURL(hostname string, port uint) url.URL
• type Driver
  • func NewDriver(url url.URL, database string) *Driver
  • func (driver *Driver) CloseConnection(ctx context.Context) error
  • func (driver *Driver) IsAlive(ctx context.Context) bool
  • func (driver *Driver) OpenConnection(ctx context.Context) error
• type Repository
  • func InitialiseNewRepository(baseType reflect.Type, port uint, ...) (*Repository, error)
  • func NewRepository(baseType reflect.Type, driver *Driver, collection string, idField string) (*Repository, error)
  • func (r *Repository) Delete(ctx context.Context, f interfaces.Filter) (*mongo.DeleteResult, error)
  • func (r *Repository) DeleteByID(ctx context.Context, id interface{}) (*mongo.DeleteResult, error)
  • func (r *Repository) DeleteMany(ctx context.Context, f interfaces.Filter) (*mongo.DeleteResult, error)
  • func (r *Repository) Exists(ctx context.Context, f interfaces.Filter) (bool, error)
  • func (r *Repository) ExistsByID(ctx context.Context, id interface{}) (bool, error)
  • func (r *Repository) Find(ctx context.Context, f interfaces.Filter) ([]interface{}, error)
  • func (r *Repository) FindByID(ctx context.Context, id interface{}) (interface{}, error)
  • func (r *Repository) Insert(ctx context.Context, v interface{}) (*mongo.InsertOneResult, error)
  • func (r *Repository) InsertMany(ctx context.Context, v ...interface{}) (*mongo.InsertManyResult, error)
  • func (r *Repository) Type() reflect.Type
  • func (r *Repository) Update(ctx context.Context, f interfaces.Filter, changes map[string]interface{}) (*mongo.UpdateResult, error)
  • func (r *Repository) UpdateByID(ctx context.Context, id interface{}, changes map[string]interface{}) (*mongo.UpdateResult, error)

Variables

var (
	// ErrDriverNil occurs when a given driver is nil.
	ErrDriverNil = errors.New("driver must no be nil")

	// ErrCollectionEmpty occurs when the name of a given collection is empty.
	ErrCollectionEmpty = errors.New("collection must not be empty")

	// ErrDocumentNotFound occurs when a lookup does not yield a result.
	ErrDocumentNotFound = errors.New("document was not found")

	// ErrMultipleMatches occurs when a lookup
	// using a given ID yields more than one result.
	ErrMultipleMatches = errors.New("multiple matches for id")
)

Functions

func NewDatabaseURL

func NewDatabaseURL(hostname string, port uint) url.URL

NewDatabaseURL creates a new URL for connecting to a MongoDB database.

Types

type Driver

type Driver struct {
	URL      url.URL                // the URL
	Database string                 // the name of the database
	Client   *mongo.Client          // a handle representing a pool of connections to the database
	Options  *options.ClientOptions // options for configuring the client
}

A Driver is a wrapper for connecting to a MongoDB database.

func NewDriver

func NewDriver(url url.URL, database string) *Driver

NewDriver returns a new driver.

func (*Driver) CloseConnection

func (driver *Driver) CloseConnection(ctx context.Context) error

CloseConnection disconnects from the database.

It fails if there is an internal MongoDB error.

func (*Driver) IsAlive

func (driver *Driver) IsAlive(ctx context.Context) bool

IsAlive returns whether the connection to the database is still alive.

func (*Driver) OpenConnection

func (driver *Driver) OpenConnection(ctx context.Context) error

OpenConnection establishes a connection to the database.

It fails if there is an internal MongoDB error.

type Repository

type Repository struct {
	Driver *Driver // the Driver used to connect to the database
	// contains filtered or unexported fields
}

A Repository wraps the Driver and provides functionality for performing operations on the collections of a MongoDB database. It can only access one collection at a time, though.

Repository implements the Repository interface.

To allow for generic access to collections containing arbitrary data, the Repository must be provided with the underlying type of the data structure contained in the specific collection to access.

func InitialiseNewRepository

func InitialiseNewRepository(baseType reflect.Type, port uint, hostname, database, collection, idField string) (*Repository, error)

InitialiseNewRepository builds all components needed for and combines them into a Repository.

see NewRepository

func NewRepository

func NewRepository(baseType reflect.Type, driver *Driver, collection string, idField string) (*Repository, error)

NewRepository returns a new Repository upon validating the given base type and Driver.

If idField is an empty string, the default Mongo id ("_id") is used instead.

It fails if the driver is nil, or if the provided base type is not a pointer.

It also fails if collection is an empty string.

func (*Repository) Delete

func (r *Repository) Delete(ctx context.Context, f interfaces.Filter) (*mongo.DeleteResult, error)

Delete deletes at most one document in r's collection matching f.

It fails if there is an internal MongoDB error.

func (*Repository) DeleteByID

func (r *Repository) DeleteByID(ctx context.Context, id interface{}) (*mongo.DeleteResult, error)

DeleteByID deletes at most one document in r's collection having the given id.

It fails if there is an internal MongoDB error.

func (*Repository) DeleteMany

func (r *Repository) DeleteMany(ctx context.Context, f interfaces.Filter) (*mongo.DeleteResult, error)

DeleteMany deletes all documents in r's collection matching f.

It fails if there is an internal MongoDB error.

func (*Repository) Exists

func (r *Repository) Exists(ctx context.Context, f interfaces.Filter) (bool, error)

Exists returns whether a document matching f exists in r's collection.

It fails if the queried data cannot be decoded, or if there is an internal MongoDB error.

func (*Repository) ExistsByID

func (r *Repository) ExistsByID(ctx context.Context, id interface{}) (bool, error)

ExistsByID returns whether at least one document having the given id exists in r's collection.

It fails if the queried data cannot be decoded, or if there is an internal MongoDB error.

func (*Repository) Find

func (r *Repository) Find(ctx context.Context, f interfaces.Filter) ([]interface{}, error)

Find finds all documents in r's collection matching f and decodes each into a value of r's base type.

It fails if the queried data cannot be decoded, or if there is an internal MongoDB error.

func (*Repository) FindByID

func (r *Repository) FindByID(ctx context.Context, id interface{}) (interface{}, error)

FindByID finds a document in r's collection that has the given id and decodes it into a value of r's base type.

It fails if

1. there is an internal MongoDB error (in which case the respective error is returned), or

2. if no document is found (in which case ErrDocumentNotFound is returned), or

3. if multiple documents are found (in which case ErrMultipleMatches is returned).

func (*Repository) Insert

func (r *Repository) Insert(ctx context.Context, v interface{}) (*mongo.InsertOneResult, error)

Insert inserts a value into r's collection.

It decodes v into a value of r's base type, which is subsequently inserted into r's collection.

It fails if v cannot be decoded into r's base type, or if there is an internal MongoDB error.

func (*Repository) InsertMany

func (r *Repository) InsertMany(ctx context.Context, v ...interface{}) (*mongo.InsertManyResult, error)

InsertMany inserts a variadic number of values into r's collection.

It decodes each element in v into a value of r's base type, which is subsequently inserted into r's collection.

It fails if an element of v cannot be decoded into r's base type, or if there is an internal MongoDB error.

func (*Repository) Type

func (r *Repository) Type() reflect.Type

Type returns a pointer to r's base type, which has the same type as the data stored in r's collection.

func (*Repository) Update

func (r *Repository) Update(ctx context.Context, f interfaces.Filter, changes map[string]interface{}) (*mongo.UpdateResult, error)

Update updates at most one document in r's collection matching f, using the given changes.

It decodes changes into a value of r's base type, which is subsequently used to update the first document matching f.

It fails if there is an internal MongoDB error.

func (*Repository) UpdateByID

func (r *Repository) UpdateByID(ctx context.Context, id interface{}, changes map[string]interface{}) (*mongo.UpdateResult, error)

UpdateByID updates at most one document in r's collection that has the given id.

It falls back to the Repository's Update method, using the provided id as a filter.

It fails if there is an internal MongoDB error.