history

README

gorm history

History is used to keep a history record of your GORM models. Each model must be associated with an history model which is a copy of the modified record.

Install

go get github.com/vcraescu/gorm-history

Usage

1. Register the plugin using history.Register(db):

plugin, err := Register(db) // db is a *gorm.DB
if err != nil {
    panic(err)
}

1. Define your model and history model:

type Person struct {
	gorm.Model
	FirstName string
	LastName  string
	Address   *string
}

type PersonHistory struct {
	gorm.Model
	history.Entry

	FirstName string
	LastName  string
	Address   *string
}

1. Your model must implement history.Recordable interface:

func (Person) CreateHistory() interface{} {
	return PersonHistory{}
}

1. Changes after calling Create, Save, Update will be tracked.

Note: By default, the plugin will use time based versioning function for your history record which might not be 100% accurate in some cases but it is faster because it doesn't require to query the db history table at all.

Configuration

Versioning

• history.TimedVersionFunc - It returns the nanonseconds value when the create/update happens;
• history.IncrementedVersionFunc - It returns the maximum + 1 of current version column. If you use this versioning method than you must tag your history model fields (or embed history.Entry struct) like this instead of implementing the history.History interface:

type PersonHistory struct {
	gorm.Model
	history.Entry
}

// or 
type PersonHistory struct {
	gorm.Model

	Version  Version `gorm-history:"version"`
	ObjectID uint    `gorm:"index" gorm-history:"objectID"`
	Action   Action  `gorm:"type: string" gorm-history:"action"`
}

You can change the versioning function when you register the plugin:

plugin, err := Register(db, history.WithVersionFunc(history.IncrementedVersionFunc)) // db is a *gorm.DB
if err != nil {
    panic(err)
}

Copying

• history.DefaultCopyFunc - copies all the values of the recordable model to history model.

You can change the copy function when you register the plugin if you defined your own function:

func myCopyFunc(r Recordable, history interface{}) error {
    // ...
}

//...

plugin, err := Register(db, history.WithCopyFunc(myCopyFunc)) // db is a *gorm.DB
if err != nil {
    panic(err)
}

License

gorm-history is licensed under the MIT License.

Documentation

Index

• Constants
• func DefaultCopyFunc(r Recordable, h interface{}) error
• func GetHistoryFields(i interface{}) []reflect.StructField
• type Action
• type Config
• type ConfigFunc
  • func WithCopyFunc(fn CopyFunc) ConfigFunc
  • func WithVersionFunc(fn VersionFunc) ConfigFunc
• type Context
• type CopyFunc
• type Entry
  • func (l *Entry) SetHistoryAction(action Action)
  • func (l *Entry) SetHistoryObjectID(id interface{})
  • func (l *Entry) SetHistoryVersion(version Version)
• type FieldNotFoundError
  • func (e FieldNotFoundError) Error() string
• type History
• type Option
• type Plugin
  • func Register(db *gorm.DB, configFuncs ...ConfigFunc) Plugin
  • func (p Plugin) Register()
• type Recordable
• type Version
  • func IncrementedVersionFunc(ctx Context) (Version, error)
  • func TimedVersionFunc(ctx Context) (Version, error)
• type VersionFunc

Constants

const (
	Tag              = "gorm-history"
	FieldTagObjectID = "objectID"
	FieldTagVersion  = "version"
	FieldTagAction   = "action"
)

Functions

func DefaultCopyFunc

func DefaultCopyFunc(r Recordable, h interface{}) error

func GetHistoryFields

func GetHistoryFields(i interface{}) []reflect.StructField

Types

type Action

type Action string

const (
	ActionCreate Action = "create"
	ActionUpdate Action = "update"
	ActionDelete Action = "delete"
)

type Config

type Config struct {
	VersionFunc VersionFunc
	CopyFunc    CopyFunc
}

type ConfigFunc

type ConfigFunc func(c *Config)

func WithCopyFunc

func WithCopyFunc(fn CopyFunc) ConfigFunc

func WithVersionFunc

func WithVersionFunc(fn VersionFunc) ConfigFunc

type Context

type Context struct {
	Object  Recordable
	History interface{}
	Action  Action
	Scope   *gorm.Scope
}

type CopyFunc

type CopyFunc func(r Recordable, h interface{}) error

type Entry

type Entry struct {
	Version  Version `gorm-history:"version"`
	ObjectID uint    `gorm:"index" gorm-history:"objectID"`
	Action   Action  `gorm:"type: string" gorm-history:"action"`
}

func (*Entry) SetHistoryAction

func (l *Entry) SetHistoryAction(action Action)

func (*Entry) SetHistoryObjectID

func (l *Entry) SetHistoryObjectID(id interface{})

func (*Entry) SetHistoryVersion

func (l *Entry) SetHistoryVersion(version Version)

type FieldNotFoundError

type FieldNotFoundError struct {
	// contains filtered or unexported fields
}

func (FieldNotFoundError) Error

func (e FieldNotFoundError) Error() string

type History

type History interface {
	SetHistoryVersion(version Version)
	SetHistoryObjectID(id interface{})
	SetHistoryAction(action Action)
}

type Option

type Option struct {
}

type Plugin

type Plugin struct {
	VersionFunc VersionFunc
	CopyFunc    CopyFunc
	// contains filtered or unexported fields
}

func Register

func Register(db *gorm.DB, configFuncs ...ConfigFunc) Plugin

func (Plugin) Register

func (p Plugin) Register()

type Recordable

type Recordable interface {
	CreateHistory() interface{}
}

type Version

type Version int64

func IncrementedVersionFunc

func IncrementedVersionFunc(ctx Context) (Version, error)

func TimedVersionFunc

func TimedVersionFunc(ctx Context) (Version, error)

type VersionFunc

type VersionFunc func(context Context) (Version, error)