README
¶
friendlymongo
MongoDB and Golang made easy (maybe).
Installation
go get -u github.com/pmatteo/friendlymongo
Note that friendlymongo is tested on Go 1.18 and 1.22 using different vversion of MongoDB.
Usage
You can find a simple exmaple here.
Client
friendlymongo has a simple way to handle mongo.Client instance as a singelton. You can set the instance using setInstance(url) method and then get it everywhere with GetInstance().
It uses a wrapper class called MongoClient, to access the client instance use GetInstance().Client() or to get a new mongo.Database instance use GetInstance().Database(dbName).
i := friendlymongo.SetInstance("mongodb://username:password@localhost:27017")
c := i.Client()
db := i.Database("user")
or
friendlymongo.SetInstance("mongodb://username:password@localhost:27017")
c := friendlymongo.GetInstance().Client()
db := friendlymongo.GetInstance().Database("user")
Model
Model is an interface that defines a series of method that every struct must implemets to being able to be used by
the repository implmenetation.
type Model interface {
OnCreate()
OnUpdate()
OnReplace()
}
The library also comes with a simple BaseModel whcih already handels ObjectID, created and updated timestamp that can be used.
type UserProfile struct {
*friendlymongo.BaseModel
// Other fields
Name string
Surname string
Email string
BirthDate time.Time
}
Repository
The main goal of the package is allow basic Mongo functionalities access without tons of boilarplate code.
The implementation of the repository pattern using go generics is a way to have some operations mapped and accessible without any effort other than define the data structure you have to deal with.
// retrieve a BaseRepository instance fot the userProfile type
repo := friendlymongo.NewBaseRepository(db, "userProfile", &userProfile{})
...
user := NewUserProfile("John","Doe","john.doe@test.com",birthday)
// Insert the user into the database
err := repo.InsertOne(context.Background(), user)
if err != nil {
panic(err)
}
Pipeline Stage Builder
BaseRepository offers an Aggregate method for Mongo's aggregation pipelines feature. It requires an instance of mongo.Pipeline as argument.
For some basic (or even not) pipeline, friendlymongo implements a simple stage builder that ìwould help developers create their stages in a more structured way and readable way.
pipeline := friendlymongo.
NewStageBuilder().
Match("name_filter", bson.M{"name": "John"}).
Lookup("roles_lookup", bson.M{
"from": "user_role",
"localField": "_id",
"foreignField": "fk",
"as": "role",
}).
Match("filter_admin", bson.M{"role.name": "admin"}).
Build()
Documentation
¶
Index ¶
- type BaseModel
- type BaseRepository
- func (r *BaseRepository[T]) Aggregate(ctx context.Context, pipeline mongo.Pipeline, result interface{}) error
- func (r *BaseRepository[T]) Delete(ctx context.Context, filter interface{}) (int64, error)
- func (r *BaseRepository[T]) Find(ctx context.Context, filter interface{}) ([]T, error)
- func (r *BaseRepository[T]) FindOne(ctx context.Context, filter interface{}) (T, error)
- func (r *BaseRepository[T]) InsertMany(ctx context.Context, documents []T) error
- func (r *BaseRepository[T]) InsertOne(ctx context.Context, document T) error
- func (r *BaseRepository[Model]) ReplaceOne(ctx context.Context, filter interface{}, replacement Model) error
- func (r *BaseRepository[T]) UpdateOne(ctx context.Context, filters interface{}, update interface{}) (T, error)
- type Model
- type MongoClient
- type MongoRepository
- type StageBuilder
- func (pb *StageBuilder) AddStage(id string, stageType string, filters interface{}) *StageBuilder
- func (pb *StageBuilder) Append(id string, filters interface{}) *StageBuilder
- func (pb *StageBuilder) Build() mongo.Pipeline
- func (pb *StageBuilder) Count(id string, filter string) *StageBuilder
- func (pb *StageBuilder) Group(id string, filters interface{}) *StageBuilder
- func (pb *StageBuilder) Limit(id string, filters interface{}) *StageBuilder
- func (pb *StageBuilder) Lookup(id string, filters bson.M) *StageBuilder
- func (pb *StageBuilder) Match(id string, filters interface{}) *StageBuilder
- func (pb *StageBuilder) Project(id string, filters interface{}) *StageBuilder
- func (pb *StageBuilder) Skip(id string, filters interface{}) *StageBuilder
- func (pb *StageBuilder) Sort(id string, filters interface{}) *StageBuilder
- func (pb *StageBuilder) Stages() []*stage
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BaseModel ¶
type BaseModel struct {
// ID must have bson tag `omitempty` to allow the document to either have a database generated ID or
// a custom one, and being elegible for `ReplaceOne`. See method `ReplaceOne` in `BaseRepository` for more info.
ID primitive.ObjectID `json:"id" bson:"_id,omitempty"`
CreatedAt time.Time `json:"createdAt" bson:"createdAt"`
UpdatedAt time.Time `json:"updatedAt" bson:"updatedAt"`
}
func NewBaseModel ¶
func NewBaseModel() *BaseModel
type BaseRepository ¶
type BaseRepository[T Model] struct { // contains filtered or unexported fields }
BaseRepository is a base implementation of the MongoRepository interface.
func NewBaseRepository ¶
func NewBaseRepository[T Model](db *mongo.Database, collectionName string, t T) *BaseRepository[T]
NewBaseRepository creates a new instance of BaseRepository.
func (*BaseRepository[T]) Aggregate ¶
func (r *BaseRepository[T]) Aggregate(ctx context.Context, pipeline mongo.Pipeline, result interface{}) error
Aggregate runs an aggregation framework pipeline on the collection.
func (*BaseRepository[T]) Delete ¶
func (r *BaseRepository[T]) Delete(ctx context.Context, filter interface{}) (int64, error)
Delete deletes multiple documents from the collection.
func (*BaseRepository[T]) Find ¶
func (r *BaseRepository[T]) Find(ctx context.Context, filter interface{}) ([]T, error)
Find finds multiple documents in the collection.
func (*BaseRepository[T]) FindOne ¶
func (r *BaseRepository[T]) FindOne(ctx context.Context, filter interface{}) (T, error)
FindOne finds a single document in the collection.
func (*BaseRepository[T]) InsertMany ¶
func (r *BaseRepository[T]) InsertMany(ctx context.Context, documents []T) error
InsertMany inserts multiple documents into the collection.
func (*BaseRepository[T]) InsertOne ¶
func (r *BaseRepository[T]) InsertOne(ctx context.Context, document T) error
InsertOne inserts a single document into the collection.
The document parameter must be a pointer to a struct that implements the Model interface.
func (*BaseRepository[Model]) ReplaceOne ¶
func (r *BaseRepository[Model]) ReplaceOne(ctx context.Context, filter interface{}, replacement Model) error
ReplaceOne replaces a single document in the collection. Replaced document must have the same ID as the one being replaced or not have it serializible at all. It is strongly suggested to have the ID field with the `omitempty` bson tag in case of structs.
type MongoClient ¶
type MongoClient struct {
// contains filtered or unexported fields
}
MongoClient is a struct to manage the database connection
func GetInstance ¶
func GetInstance() *MongoClient
GetInstance returns the singleton instance of DatabaseConnection
func SetInstance ¶
func SetInstance(uri string) *MongoClient
SetInstance initializes a new database connection
func (*MongoClient) Client ¶
func (c *MongoClient) Client() *mongo.Client
func (*MongoClient) Connect ¶
func (c *MongoClient) Connect() error
Connect opens a connection to the database
func (*MongoClient) Disconnect ¶
func (c *MongoClient) Disconnect() error
type MongoRepository ¶
type MongoRepository[T Model] interface { // InsertOne inserts a single document into the collection. InsertOne(ctx context.Context, document Model) error // InsertMany inserts multiple documents into the collection. InsertMany(ctx context.Context, documents []Model) error // FindOne finds a single document in the collection. FindOne(ctx context.Context, filter interface{}) (Model, error) // Find finds multiple documents in the collection. Find(ctx context.Context, filter interface{}) ([]Model, error) // UpdateOne finds a single document and updates it. UpdateOne(ctx context.Context, filters interface{}, update interface{}) (Model, error) // Delete deletes multiple documents from the collection. Delete(ctx context.Context, filter interface{}) (int64, error) // ReplaceOne replaces a single document in the collection. ReplaceOne(ctx context.Context, filter interface{}, replacement T) error // Aggregate runs an aggregation framework pipeline on the collection. Aggregate(ctx context.Context, pipeline mongo.Pipeline, result interface{}) error }
MongoRepository is an interface that defines the methods for interacting with a MongoDB collection.
type StageBuilder ¶
type StageBuilder struct {
// contains filtered or unexported fields
}
func NewStageBuilder ¶
func NewStageBuilder() *StageBuilder
func (*StageBuilder) AddStage ¶
func (pb *StageBuilder) AddStage(id string, stageType string, filters interface{}) *StageBuilder
func (*StageBuilder) Append ¶
func (pb *StageBuilder) Append(id string, filters interface{}) *StageBuilder
func (*StageBuilder) Build ¶
func (pb *StageBuilder) Build() mongo.Pipeline
func (*StageBuilder) Count ¶
func (pb *StageBuilder) Count(id string, filter string) *StageBuilder
func (*StageBuilder) Group ¶
func (pb *StageBuilder) Group(id string, filters interface{}) *StageBuilder
func (*StageBuilder) Limit ¶
func (pb *StageBuilder) Limit(id string, filters interface{}) *StageBuilder
func (*StageBuilder) Lookup ¶
func (pb *StageBuilder) Lookup(id string, filters bson.M) *StageBuilder
func (*StageBuilder) Match ¶
func (pb *StageBuilder) Match(id string, filters interface{}) *StageBuilder
func (*StageBuilder) Project ¶
func (pb *StageBuilder) Project(id string, filters interface{}) *StageBuilder
func (*StageBuilder) Skip ¶
func (pb *StageBuilder) Skip(id string, filters interface{}) *StageBuilder
func (*StageBuilder) Sort ¶
func (pb *StageBuilder) Sort(id string, filters interface{}) *StageBuilder
func (*StageBuilder) Stages ¶
func (pb *StageBuilder) Stages() []*stage
Source Files