README
¶
Loggable
Loggable is used to helps tracking changes and history of your GORM models.
It creates change_logs table in your database and writes to all loggable models when they are changed.
More documentation is available in godoc.
Usage
- Register plugin using
loggable.Register(db).
plugin, err := Register(database) // database is a *gorm.DB
if err != nil {
panic(err)
}
- Add (embed)
loggable.LoggableModelto your GORM model.
type User struct{
Id uint
CreatedAt time.Time
// some other stuff...
loggable.LoggableModel
}
- Changes after calling Create, Save, Update, Delete will be tracked.
Customization
You may add additional fields to change logs, that should be saved.
First, embed loggable.LoggableModel to your model wrapper or directly to GORM model.
type CreatedByLog struct {
// Public field will be catches by GORM and will be saved to main table.
CreatedBy string
// Hided field because we do not want to write this to main table,
// only to change_logs.
createdByPass string
loggable.LoggableModel
}
After that, shadow LoggableModel's Meta() method by writing your realization, that should return structure with your information.
type CreatedByLog struct {
CreatedBy string
createdByPass string
loggable.LoggableModel
}
func (m CreatedByLog) Meta() interface{} {
return struct { // You may define special type for this purposes, here we use unnamed one.
CreatedBy string
CreatedByPass string // CreatedByPass is a public because we want to track this field.
}{
CreatedBy: m.CreatedBy,
CreatedByPass: m.createdByPass,
}
}
Options
LazyUpdate
Option LazyUpdate allows save changes only if they big enough to be saved.
Plugin compares the last saved object and the new one, but ignores changes was made in fields from provided list.
ComputeDiff
Option ComputeDiff allows to only save the changes into the RawDiff field. This options is only relevant during update
operations. Only fields tagged with gorm-loggable:true will be taken in account. If the object does not have any field
tagged with gorm-loggable:true then the column will always be NULL.
e.g.
type Person struct {
FirstName string `gorm-loggable:true`
LastName string `gorm-loggable:true`
Age int `gorm-loggable:true`
}
Let's say you change person FirstName from John to Jack and its Age from 30 to 40.
ChangeLog.RawDiff will be populated with the following:
{
"FirstName": "Jack",
"Age": 40,
}
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ToSnakeCase = toSomeCase("_")
Functions ¶
func ToLowerFirst ¶ added in v1.3.0
Types ¶
type ChangeLog ¶
type ChangeLog struct {
// Primary key of change logs.
ID uuid.UUID `gorm:"primary_key;"`
// Timestamp, when change log was created.
CreatedAt time.Time `gorm:"DEFAULT:current_timestamp"`
// Action type.
// On write, supports only 'create', 'update', 'delete',
// but on read can be anything.
Action string
// ID of tracking object.
// By this ID later you can find all object (database row) changes.
ObjectID string `gorm:"index"`
// Reflect name of tracking object.
// It does not use package or module name, so
// it may be not unique when use multiple types from different packages but with the same name.
ObjectType string `gorm:"index"`
// Raw representation of tracking object.
// todo(@sas1024): Replace with []byte, to reduce allocations. Would be major version.
RawObject string `gorm:"type:JSON"`
// Raw representation of tracking object's meta.
// todo(@sas1024): Replace with []byte, to reduce allocations. Would be major version.
RawMeta string `gorm:"type:JSON"`
// Raw representation of diff's.
// todo(@sas1024): Replace with []byte, to reduce allocations. Would be major version.
RawDiff string `gorm:"type:JSON"`
// Free field to store something you want, e.g. who creates change log.
// Not used field in gorm-loggable, but gorm tracks this field.
CreatedBy string `gorm:"index"`
// Field Object would contain prepared structure, parsed from RawObject as json.
// Use RegObjectType to register object types.
Object interface{} `gorm:"-"`
// Field Meta would contain prepared structure, parsed from RawMeta as json.
// Use RegMetaType to register object's meta types.
Meta interface{} `gorm:"-"`
}
ChangeLog is a main entity, which used to log changes. Commonly, ChangeLog is stored in 'change_logs' table.
func (ChangeLog) Diff ¶ added in v1.5.0
func (l ChangeLog) Diff() (UpdateDiff, error)
Diff returns parsed to map[string]interface{} diff representation from field RawDiff. To unmarshal diff to own structure, manually use field RawDiff.
type Interface ¶ added in v1.5.0
type Interface interface {
// Meta should return structure, that can be converted to json.
Meta() interface{}
// enable/disable loggable
Enable(v bool)
// contains filtered or unexported methods
}
Interface is used to get metadata from your models.
type LoggableModel ¶
type LoggableModel struct {
Disabled bool `gorm:"-" json:"-"`
}
LoggableModel is a root structure, which implement Interface. Embed LoggableModel to your model so that Plugin starts tracking changes.
func (LoggableModel) Enable ¶ added in v1.5.0
func (l LoggableModel) Enable(v bool)
func (LoggableModel) Meta ¶ added in v1.5.0
func (LoggableModel) Meta() interface{}
type Option ¶ added in v1.3.0
type Option func(options *options)
Option is a generic options pattern.
func ComputeDiff ¶ added in v1.5.0
func ComputeDiff() Option
Option ComputeDiff allows you also write differences between objects on update operations. ComputeDiff not reads records from db, it used only as cache on plugin side. So it does not track changes outside plugin.
func LazyUpdate ¶ added in v1.5.0
Option LazyUpdate allows you to skip update operations when nothing was changed. Parameter 'fields' is list of sql field names that should be ignored on updates.
func RegMetaType ¶ added in v1.5.0
RegMetaType works like RegObjectType, but for field RawMeta. RegMetaType maps object to type name, that is used in field Type of ChangeLog struct. On read change log operations, if plugin finds registered object type, by its name from db, it unmarshal field RawMeta to Meta field via json.Unmarshal.
To access decoded object, e.g. `MyClientMeta`, use type casting: `changeLog.Meta.(MyClientMeta)`.
func RegObjectType ¶ added in v1.5.0
RegObjectType maps object to type name, that is used in field Type of ChangeLog struct. On read change log operations, if plugin finds registered object type, by its name from db, it unmarshal field RawObject to Object field via json.Unmarshal.
To access decoded object, e.g. `ReallyFunnyClient`, use type casting: `changeLog.Object.(ReallyFunnyClient)`.
type Plugin ¶ added in v1.5.0
type Plugin struct {
// contains filtered or unexported fields
}
Plugin is a hook for gorm.
func Register ¶
Register initializes Plugin for provided gorm.DB. There is also available some options, that should be passed there. Options cannot be set after initialization.
func (*Plugin) GetLastRecord ¶ added in v1.5.0
GetLastRecord returns last by creation time (CreatedAt field) change log by provided object id. Flag prepare allows to decode content of Raw* fields to direct fields, e.g. RawObject to Object.
Source Files