gomodel

GoModel

See CHANGELOG.md for the release history and UPGRADING.md for migration guides between major versions.

Installation

go get bitbucket.org/amotus/gomodel/v2@latest

Users still on v1 can keep importing bitbucket.org/amotus/gomodel; see Versioning below.

Usages

Implement the ModelInterface in your model

type MyModel struct {
    Id           int64           `gorm:"primaryKey"`
    DeletedAt    *gorm.DeletedAt `json:"deleted_at"`
}

func (d *MyModel) GetId() int64 {
	return d.Id
}
func (d *MyModel) SetId(id int64) {
	d.Id = id
}

func (d *MyModel) Query(db *gorm.DB, withTrash bool) *gorm.DB {
	if withTrash {
		return db.Unscoped().Model(&MyModel{})
	}
	return db.Model(&MyModel{})
}

The primary key is not restricted to int64: any comparable type works, for example uuid.UUID or string. Just declare GetId / SetId with that type.

Use Model[M, K]

once your struct implement the interface ModelInterface, you can use the New function to get a Model[M, K] object, where M is your model type and K the type of its primary key. Both are inferred by the compiler.

modelPointer := gomodel.New(db, &MyModel{})

It is recommended to define a helper function in your model namespace

func NewMyModel(db *gorm.DB) *gomodel.Model[*MyModel, int64] {
    return gomodel.New(db, &MyModel{})
}

Use the Model[M, K] object

// Create a new model
modelPointer := NewMyModel(db)

// Create a new model with data, *data is not saved to the database
modelPointer := NewMyModel(db).Set(&MyModel{
    Id: 1,
})

Model[M, K] methods

Save model to the database

Save is not chainable, it returns error if any

err := modelPointer.Save()
if err != nil {
    // Handle error
}

Create

Use directly the Create function to save into database a new model.

Create is chainable, it returns the model and in case of error, it is embedded in the model:

modelPointer := NewMyModel(db).Create(&MyModel{
    Id: 1,
})

if modelPointer.Err != nil {
    // Handle error
}

Find

Get a model from the database

Find is chainable, it returns the model and in case of error, it is embedded in the model:

modelStruct := NewMyModel(db).Find(1)
if modelPointer.Err != nil {
    // Handle error
}

OrderBy

Set the order of the objects returned by the query

OrderBy is chainable but must be used after a query is set:

all, err := NewMyModel(db).OrderBy("id", gomodel.ASC).All()
if err != nil {
    // Handle error
}

First

Get a model from the database using the first row corresponding to the query

First is chainable, it returns the model and in case of error, it is embedded in the model:

modelStruct := NewMyModel(db).First()
if modelPointer.Err != nil {
    // Handle error
}

modelStruct := NewMyModel(db).Where("id = ?", 1).First()
if modelPointer.Err != nil {
    // Handle error
}

Select

Select allows you to specify the fields that you want to retrieve from database. Otherwise, GORM will select all fields by default.

_ = NewMyModel(db).Select("name", "age").First()
_ = NewMyModel(db).Select([]string{"name", "age"}).First()
_ = NewMyModel(db).Select("COALESCE(age,?)", 42).First()

Grouping Where Conditions

modelStruct, err := NewMyModel(db).WhereGroup(func(q *gorm.DB) *gorm.DB { return q.Where("name = ?", "jane").Or("name = ?", "doe") }).First()
if err != nil {
    // Handle error
}

All

Get all model from the database

// perform any filter on the db object before creating the model object.
//db = db.Scopes(isProject(1)) 

items, errDb := NewMyModel(db).All()
if errDb != nil {
    // Handle error
}
for _, item := range items {
    fmt.println(item)
}

Take & Skip

Limits the number of rows returned by the query

items, errDb := NewMyModel(db).Take(10).Skip(5).All()

Count

Count the number of rows returned by the query

c, errDb := NewMyModel(db).Count()

Fresh

Refresh the model from the database

Fresh is chainable, it returns the model and in case of error, it is embedded in the model:

modelPointer.Fresh()
if modelPointer.Err != nil {
    // Handle error
}

Relations

Load relations of a model using the With function

item, errDb := NewMyModel(db).With("relation1", "relation2").Find(1).Get()
if errDb != nil {
    // Handle error
}
fmt.println(item.Relation1, item.Relation2)

If you already have a model loaded, you can use the Load function to add relations immediately

modelPointer.Load("relation1", "relation2") //Load will perform a Fresh() after adding relations

item, errDb := modelPointer.Get()
if errDb != nil {
    // Handle error
}
fmt.println(item.Relation1, item.Relation2)

Update

Update a model in database.

Update is chainable, it returns the model and in case of error, it is embedded in the model:

modelPointer := NewMyModel(db).Update(&MyModel{
    Name: "updated name",
})

if modelPointer.Err != nil {
    // Handle error
}

NOTE Update will not refresh the model, you need to call Fresh() to get the updated model from the database

NOTE When updating with struct, GORM will only update non-zero fields. You might want to use updateAll to update all attributes

UpdateAll

modelPointer := NewMyModel(db).UpdateAll(&MyModel{
    Name: "updated name",
	Count: 0,
})

if modelPointer.Err != nil {
    // Handle error
}

Count property (and also all non-set properties) will be updated to 0 while using updateAll

Create or Update

CreateOrUpdate is chainable, it returns the model and in case of error, it is embedded in the model:

modelPointer := NewMyModel(db).CreateOrUpdate(&MyModel{
    Id: 1,
})
if modelPointer.Err != nil {
    // Handle error
}

Delete a model

given the model id 1

errDb := modelPointer.Delete()
if errDb != nil {
    // Handle error
}

Restore a model

errDb := modelPointer.Restore()
if errDb != nil {
    // Handle error
}

Soft Delete

Use WithTrash to query model with deleted items included

exist, errDb := NewMyModel(db).WithTrash().Set(&MyModel{ Id: 1}).Exist()
if errDb != nil {
    // Handle error
}

Find methods doesn't use WithTrash, it will return the model only if it isn't trashed

Look at the model_test.go file for more examples

Versioning

This module follows Semantic Versioning and releases are documented in CHANGELOG.md.

Major versions use the major branch strategy: main always holds the latest major version, and each previous major keeps a maintenance branch.

If you installed v1 from the default branch (@main), pin it to @v1.2.12 instead — main now holds v2.

Breaking changes are only released in a new major version, with a migration guide in UPGRADING.md.

Maintainers

• Dominic Plourde

License

Proprietary © Dimonoff