Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/qiniu/qmgo
Qmgo - The Go driver for MongoDB. It‘s based on official mongo-go-driver but easier to use like Mgo.
https://github.com/qiniu/qmgo
database driver go mgo mongo-go-driver mongodb mongodb-database mongodb-driver
Last synced: 1 day ago
JSON representation
Qmgo - The Go driver for MongoDB. It‘s based on official mongo-go-driver but easier to use like Mgo.
- Host: GitHub
- URL: https://github.com/qiniu/qmgo
- Owner: qiniu
- License: apache-2.0
- Created: 2020-08-04T09:06:00.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-10-31T09:14:38.000Z (about 1 month ago)
- Last Synced: 2024-12-04T16:46:00.763Z (9 days ago)
- Topics: database, driver, go, mgo, mongo-go-driver, mongodb, mongodb-database, mongodb-driver
- Language: Go
- Homepage:
- Size: 479 KB
- Stars: 1,322
- Watchers: 27
- Forks: 155
- Open Issues: 51
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-go - qmgo - The MongoDB driver for Go. It‘s based on official MongoDB driver but easier to use like Mgo. (Database Drivers / NoSQL Database Drivers)
- awesome-go - qmgo - The MongoDB driver for Go. It‘s based on official MongoDB driver but easier to use like Mgo. Stars:`1.3K`. (Database Drivers / NoSQL Database Drivers)
- awesome-golang-repositories - qmgo - The Go driver for MongoDB. It�ｽ鈆ｦ based on official mongo-go-driver but easier to use like Mgo. (Repositories)
- awesome-go-extra - qmgo - The Go driver for MongoDB. It‘s based on official mongo-go-driver but easier to use like Mgo.|954|120|32|2020-08-04T09:06:00Z|2022-08-16T07:33:36Z| (Generators / NoSQL Database Drivers)
README
# Qmgo
[](https://travis-ci.org/qiniu/qmgo)
[](https://codecov.io/gh/qiniu/qmgo)
[](https://goreportcard.com/report/github.com/qiniu/qmgo)
[](https://github.com/qiniu/qmgo/releases)
[](https://pkg.go.dev/github.com/qiniu/qmgo?tab=doc)
English | [简体中文](README_ZH.md)
`Qmgo` is a `Go` `driver` for `MongoDB` . It is based on [MongoDB official driver](https://github.com/mongodb/mongo-go-driver), but easier to use like [mgo](https://github.com/go-mgo/mgo) (such as the chain call).
- `Qmgo` allows users to use the new features of `MongoDB` in a more elegant way.
- `Qmgo` is the first choice for migrating from `mgo` to the new `MongoDB driver` with minimal code changes.
## Requirements
-`Go 1.10` and above.
-`MongoDB 2.6` and above.
## Features
- CRUD to documents, with all official supported options
- Sort、limit、count、select、distinct
- Transactions
- Hooks
- Automatically default and custom fields
- Predefine operator keys
- Aggregate、indexes operation、cursor
- Validation tags
- Plugin
## Installation
- Use `go mod` to automatically install dependencies by `import github.com/qiniu/qmgo`
Or
- Use `go get github.com/qiniu/qmgo`
## Usage
- Start
`import` and create a new connection
```go
import (
"context"
"github.com/qiniu/qmgo"
)
ctx := context.Background()
client, err := qmgo.NewClient(ctx, &qmgo.Config{Uri: "mongodb://localhost:27017"})
db := client.Database("class")
coll := db.Collection("user")
```
If your connection points to a fixed database and collection, recommend using the following way to initialize the connection.
All operations can be based on `cli`:
```go
cli, err := qmgo.Open(ctx, &qmgo.Config{Uri: "mongodb://localhost:27017", Database: "class", Coll: "user"})
```
***The following examples will be based on `cli`, if you use the first way for initialization, replace `cli` with `client`、`db` or `coll`***
Make sure to defer a call to Disconnect after instantiating your client:
```go
defer func() {
if err = cli.Close(ctx); err != nil {
panic(err)
}
}()
```
- Create index
Before doing the operation, we first initialize some data:
```go
type UserInfo struct {
Name string `bson:"name"`
Age uint16 `bson:"age"`
Weight uint32 `bson:"weight"`
}
var userInfo = UserInfo{
Name: "xm",
Age: 7,
Weight: 40,
}
```
Create index
```go
cli.CreateOneIndex(context.Background(), options.IndexModel{Key: []string{"name"}})
cli.CreateIndexes(context.Background(), []options.IndexModel{{Key: []string{"id2", "id3"}}})
```
- Insert a document
```go
// insert one document
result, err := cli.InsertOne(ctx, userInfo)
```
- Find a document
```go
// find one document
one := UserInfo{}
err = cli.Find(ctx, bson.M{"name": userInfo.Name}).One(&one)
```
- Delete documents
```go
err = cli.Remove(ctx, bson.M{"age": 7})
```
- Insert multiple data
```go
// multiple insert
var userInfos = []UserInfo{
UserInfo{Name: "a1", Age: 6, Weight: 20},
UserInfo{Name: "b2", Age: 6, Weight: 25},
UserInfo{Name: "c3", Age: 6, Weight: 30},
UserInfo{Name: "d4", Age: 6, Weight: 35},
UserInfo{Name: "a1", Age: 7, Weight: 40},
UserInfo{Name: "a1", Age: 8, Weight: 45},
}
result, err = cli.Collection.InsertMany(ctx, userInfos)
```
- Search all, sort and limit
```go
// find all, sort and limit
batch := []UserInfo{}
cli.Find(ctx, bson.M{"age": 6}).Sort("weight").Limit(7).All(&batch)
```
- Count
````go
count, err := cli.Find(ctx, bson.M{"age": 6}).Count()
````
- Update
````go
// UpdateOne one
err := cli.UpdateOne(ctx, bson.M{"name": "d4"}, bson.M{"$set": bson.M{"age": 7}})
// UpdateAll
result, err := cli.UpdateAll(ctx, bson.M{"age": 6}, bson.M{"$set": bson.M{"age": 10}})
````
- Select
````go
err := cli.Find(ctx, bson.M{"age": 10}).Select(bson.M{"age": 1}).One(&one)
````
- Aggregate
```go
matchStage := bson.D{{"$match", []bson.E{{"weight", bson.D{{"$gt", 30}}}}}}
groupStage := bson.D{{"$group", bson.D{{"_id", "$name"}, {"total", bson.D{{"$sum", "$age"}}}}}}
var showsWithInfo []bson.M
err = cli.Aggregate(context.Background(), Pipeline{matchStage, groupStage}).All(&showsWithInfo)
```
- Support All mongoDB Options when create connection
````go
poolMonitor := &event.PoolMonitor{
Event: func(evt *event.PoolEvent) {
switch evt.Type {
case event.GetSucceeded:
fmt.Println("GetSucceeded")
case event.ConnectionReturned:
fmt.Println("ConnectionReturned")
}
},
}
opt := options.Client().SetPoolMonitor(poolMonitor) // more options use the chain options.
cli, err := Open(ctx, &Config{Uri: URI, Database: DATABASE, Coll: COLL}, opt)
````
- Transactions
The super simple and powerful transaction, with features like `timeout`、`retry`:
````go
callback := func(sessCtx context.Context) (interface{}, error) {
// Important: make sure the sessCtx used in every operation in the whole transaction
if _, err := cli.InsertOne(sessCtx, bson.D{{"abc", int32(1)}}); err != nil {
return nil, err
}
if _, err := cli.InsertOne(sessCtx, bson.D{{"xyz", int32(999)}}); err != nil {
return nil, err
}
return nil, nil
}
result, err = cli.DoTransaction(ctx, callback)
````
[More about transaction](https://github.com/qiniu/qmgo/wiki/Transactions)
- Predefine operator keys
````go
// aggregate
matchStage := bson.D{{operator.Match, []bson.E{{"weight", bson.D{{operator.Gt, 30}}}}}}
groupStage := bson.D{{operator.Group, bson.D{{"_id", "$name"}, {"total", bson.D{{operator.Sum, "$age"}}}}}}
var showsWithInfo []bson.M
err = cli.Aggregate(context.Background(), Pipeline{matchStage, groupStage}).All(&showsWithInfo)
````
- Hooks
Qmgo flexible hooks:
````go
type User struct {
Name string `bson:"name"`
Age int `bson:"age"`
}
func (u *User) BeforeInsert(ctx context.Context) error {
fmt.Println("before insert called")
return nil
}
func (u *User) AfterInsert(ctx context.Context) error {
fmt.Println("after insert called")
return nil
}
u := &User{Name: "Alice", Age: 7}
_, err := cli.InsertOne(context.Background(), u)
````
[More about hooks](https://github.com/qiniu/qmgo/wiki/Hooks)
- Automatically fields
Qmgo support two ways to make specific fields automatically update in specific API
- Default fields
Inject `field.DefaultField` in document struct, Qmgo will update `createAt`、`updateAt` and `_id` in update and insert operation.
````go
type User struct {
field.DefaultField `bson:",inline"`
Name string `bson:"name"`
Age int `bson:"age"`
}
u := &User{Name: "Lucas", Age: 7}
_, err := cli.InsertOne(context.Background(), u)
// Fields with tag createAt、updateAt and _id will be generated automatically
````
- Custom fields
Define the custom fields, Qmgo will update them in update and insert operation.
```go
type User struct {
Name string `bson:"name"`
Age int `bson:"age"`
MyId string `bson:"myId"`
CreateTimeAt time.Time `bson:"createTimeAt"`
UpdateTimeAt int64 `bson:"updateTimeAt"`
}
// Define the custom fields
func (u *User) CustomFields() field.CustomFieldsBuilder {
return field.NewCustom().SetCreateAt("CreateTimeAt").SetUpdateAt("UpdateTimeAt").SetId("MyId")
}
u := &User{Name: "Lucas", Age: 7}
_, err := cli.InsertOne(context.Background(), u)
// CreateTimeAt、UpdateTimeAt and MyId will be generated automatically
// suppose Id and ui is ready
err = cli.ReplaceOne(context.Background(), bson.M{"_id": Id}, &ui)
// UpdateTimeAt will update
```
Check [examples here](https://github.com/qiniu/qmgo/blob/master/field_test.go)
[More about automatically fields](https://github.com/qiniu/qmgo/wiki/Automatically-update-fields)
- Validation tags
Qmgo Validation tags is Based on [go-playground/validator](https://github.com/go-playground/validator).
So Qmgo support [all validations on structs in go-playground/validator](https://github.com/go-playground/validator#usage-and-documentation), such as:
```go
type User struct {
FirstName string `bson:"fname"`
LastName string `bson:"lname"`
Age uint8 `bson:"age" validate:"gte=0,lte=130" ` // Age must in [0,130]
Email string `bson:"e-mail" validate:"required,email"` // Email can't be empty string, and must has email format
CreateAt time.Time `bson:"createAt" validate:"lte"` // CreateAt must lte than current time
Relations map[string]string `bson:"relations" validate:"max=2"` // Relations can't has more than 2 elements
}
```
Qmgo tags only supported in following API：
` InsertOne、InsertyMany、Upsert、UpsertId、ReplaceOne `
- Plugin
- Implement following method:
```go
func Do(ctx context.Context, doc interface{}, opType operator.OpType, opts ...interface{}) error{
// do anything
}
```
- Call Register() in package middleware, register the method `Do`
Qmgo will call `Do` before and after the [operation](operator/operate_type.go)
```go
middleware.Register(Do)
```
[Example](middleware/middleware_test.go)
The `hook`、`automatically fields` and `validation tags` in Qmgo run on **plugin**.
## `Qmgo` vs `go.mongodb.org/mongo-driver`
Below we give an example of multi-file search、sort and limit to illustrate the similarities between `qmgo` and `mgo` and the improvement compare to `go.mongodb.org/mongo-driver`.
How do we do in`go.mongodb.org/mongo-driver`:
```go
// go.mongodb.org/mongo-driver
// find all, sort and limit
findOptions := options.Find()
findOptions.SetLimit(7) // set limit
var sorts D
sorts = append(sorts, E{Key: "weight", Value: 1})
findOptions.SetSort(sorts) // set sort
batch := []UserInfo{}
cur, err := coll.Find(ctx, bson.M{"age": 6}, findOptions)
cur.All(ctx, &batch)
```
How do we do in `Qmgo` and `mgo`:
```go
// qmgo
// find all, sort and limit
batch := []UserInfo{}
cli.Find(ctx, bson.M{"age": 6}).Sort("weight").Limit(7).All(&batch)
// mgo
// find all, sort and limit
coll.Find(bson.M{"age": 6}).Sort("weight").Limit(7).All(&batch)
```
## `Qmgo` vs `mgo`
[Differences between qmgo and mgo](https://github.com/qiniu/qmgo/wiki/Differences-between-Qmgo-and-Mgo)
## Contributing
The Qmgo project welcomes all contributors. We appreciate your help!
## Communication:
- Join [qmgo discussions](https://github.com/qiniu/qmgo/discussions)