mgostore

README

mgostore

An ORM like adaptor to store structs in mongo DB. This heavily uses the external mongo library mgo

Description

This package is designed in such a way that it could be used easily to have operations on models (structs which can be stored as documents in mongo).

We would create a model called MyAwesomeModel Create a struct with the field. It should compulsorily have one field, viz., ID which is the \_id in the mongoDB storage. This is of type bson.ObjectId, so you will need to parse it into Hex string when you get it as a string from GET requests.

For fields which you do not want to show up in the json responses have the tag json:"-" Binary json tags would be used to unmarshall this struct to the mongoDb document. eg, field ActivatedDate with bson:"activated_date" will be stored in mongo with key activated_date for this field. If not specified, it automatically lower cases it, so it will then become activateddate.

For fields which you would like to be stored encrypted, simply add the tag encrypt="aes" Right now, only this option is supported for encryption

type MyAwesomeModel struct {
	ID               bson.ObjectId `json:"id" bson:"_id,omitempty"`
	MyAwesomeField   string `json:"my_awesome_field" bson:"my_awesome_field"`
	AnEncryptedField string `json:"an_encrypted_field" bson:"an_encrypted_field" encrypt:"aes"`
}

The json tag helps in marshaling and unmarshaling from and to the json responses and requests. If not specified then it will be directly the name of the field. So,

type SomeModel struct {
	SomeField string
}
=>
{
  "SomeField": ..
}

The bson tag similarly helps in marshaling and unmarshaling to mongoDB storage. If not specified, it is by default lowercased.

You need to have a method CollectionName() string on your struct. This should simply return the name of the collection in mongoDB

func (_ *MyAwesomeModel) CollectionName() string {
	return "my_awesome_models"
}

You also need to specify the config which the model should use to connect to the MongoDB. This gives you the flexibility to have multiple DB connections in the same application. This can be done by simply adding the method DBConfig().

func (_ *MyAwesomeModel) DBConfig() *mgostore.MongoConfig {
	return &mgostore.MongoConfig{
		Servers: "localhost",
		DBName: "test",
		Timeout: 500,
    		CryptoConfig: &mgostore.CryptoConfig{AESSecret: []byte("SOMEKEYSECRET")},
	}
}

Now you can store Your model to mongoDB by

mam := &MyAwesomeModel{MyAwesomeField: "some value1", AnEncryptedField: "shhhhhh"}

// Store to DB
mgostore.Create(mam)

Similarly you can perform other operations

mam := &MyAwesomeModel{Id: oId, MyAwesomeField: "some value1", AnEncryptedField: "shhhhhh"}

// update in mongoDB for the record with id 1234
mgostore.Update(mam)

// Find model from the DB
mam := &MyAwesomeModel{Id: oId}
mgostore.Find(mam)

// Find one record based on some where clause from the DB
whereClause := bson.M{"my_awesome_field": "some val"}
mam := &MyAwesomeModel
mgostore.FindBy(whereClause, mam)

// Find multiple records based on some where clause from the DB
type models []MyAwesomeModel
var models MyAwesomeModels
whereClause := bson.M{"my_awesome_field": "some val"}
mgostore.FindMany(whereClause, &models)

// Delete from storage
mgostore.Destroy(mam)

If you want nested documents then the mgo package used requires the tag bson:",inline". Consider the following example

type Person struct {
	Id            bson.ObjectId  `json:"_id" bson:"_id,omitempty"`
	Name          string  `json:"name"`
	HomeAddress   Address `json:"home_address" bson:"home_address,inline"`
	OfficeAddress Address `json:"office_address" bson:"office_address,inline"`
}

type Address struct {
	AddressLine1 string `json:"address_line_1" bson:"address_line_1"`
	AddressLine2 string `json:"address_line_2" bson:"address_line_2"`
	City         string `json:"city"`
}

Testing

First make sure you have mongoDB running on your machine. The project is maintained in govendor.

Run the tests for this package by running

govendor test +local

Documentation

Index

• Variables
• func Create(m Model) error
• func Destroy(m Model) error
• func Find(m Model) error
• func FindBy(whereClause bson.M, m Model) error
• func FindMany(whereClause bson.M, models Models, options ...int) error
• func Update(m Model) error
• type CryptoConfig
• type Model
• type Models
• type MongoConfig

Variables

var ErrInvalidId = errors.New("invalid id")

var ErrMissingCryptoSecret = errors.New("missing crypto secret")

var ErrMongoCollectionNotFetched = errors.New("mongo collection not fetched")

var ErrRecordNotFound = mgo.ErrNotFound

Functions

func Create

func Create(m Model) error

Create the model in DB

func Destroy

func Destroy(m Model) error

Delete from the DB For this to work, the model should be initialized with the correct value of Id for which to lookup in DB

func Find

func Find(m Model) error

Returns the Struct from the DB For this to work, the model should be initialized with the correct value of Id for which to lookup in DB

func FindBy

func FindBy(whereClause bson.M, m Model) error

FindBy returns a record of a model interface by a where clause passed to it. It expects an input of the whereClause as the shortened bson.M format. Check here : https://godoc.org/gopkg.in/mgo.v2/bson#M

func FindMany

func FindMany(whereClause bson.M, models Models, options ...int) error

FindBy returns many records of a model interface by a where clause passed to it. It expects the string collectionName it should look into It expects an input of the whereClause as the shortened bson.M format. Check here : https://godoc.org/gopkg.in/mgo.v2/bson#M

This method has an issue with Decryption. So Decrypt the models manually. var models []MyAwesomeModel FindMany("my_awesome_models", bson.M{"some_field": "some_field_value"}, &models)

In case limit and skip is called, then please pass them in the options parameter in the order skip, limit eg, to have no skips but to have a limit of 10

FindMany("my_awesome_models", bson.M{"some_field": "some_field_value"}, &models, -1, 10)

func Update

func Update(m Model) error

Stores the struct to DB This will update this model with all its attributes in the DB

Types

type CryptoConfig

type CryptoConfig struct {
	AESSecret []byte
}

CryptoConfig represents the configuration keys of encryption secret

type Model

type Model interface {
	// This method should return the collection name in the mongo DB where this model will be stored
	CollectionName() string

	// Should return a valid MongoConfig which contains the configuration values to connect to the DB
	DBConfig() *MongoConfig
}

Model interface represents a storable entity Two methods need to be defined for this.

type Models

type Models interface {
	// This method should return the collection name in the mongo DB where this model will be stored
	CollectionName() string

	// Should return a valid MongoConfig which contains the configuration values to connect to the DB
	DBConfig() *MongoConfig
}

A models interface represents a storable entity list of entities Two methods need to be defined for this.

type MongoConfig

type MongoConfig struct {
	// Define a comma separated array of Servers here
	Servers string
	// Define the DB Name for which the corresponding model would connect to
	DBName  string
	Timeout time.Duration
	// Specifies if the connection is SSL. This is important to use a tls.Dial function in that case due to limitations of mgo package
	IsSSL bool
	// configuration keys for encryption and decryption
	CryptoConfig *CryptoConfig
}

MongoConfig struct determines the connection to the mongo DB.