package module
Version: v0.2.11 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Jun 21, 2020 License: MIT Imports: 14 Imported by: 4,391



The fantastic ORM library for Golang, aims to be developer friendly.

go report card wercker status Open Collective Backer Open Collective Sponsor MIT license Go.Dev reference


  • Full-Featured ORM (almost)
  • Associations (Has One, Has Many, Belongs To, Many To Many, Polymorphism)
  • Hooks (Before/After Create/Save/Update/Delete/Find)
  • Preloading (eager loading)
  • Transactions
  • Composite Primary Key
  • SQL Builder
  • Auto Migrations
  • Logger
  • Extendable, write Plugins based on GORM callbacks
  • Every feature comes with tests
  • Developer Friendly

Getting Started


You can help to deliver a better GORM, check out things you can do


© Jinzhu, 2013~time.Now

Released under the MIT License




This section is empty.


View Source
var (
	// ErrRecordNotFound record not found error
	ErrRecordNotFound = errors.New("record not found")
	// ErrInvalidSQL invalid SQL error, happens when you passed invalid SQL
	ErrInvalidSQL = errors.New("invalid SQL")
	// ErrInvalidTransaction invalid transaction when you are trying to `Commit` or `Rollback`
	ErrInvalidTransaction = errors.New("no valid transaction")
	// ErrUnaddressable unaddressable value
	ErrUnaddressable = errors.New("using unaddressable value")
	// ErrNotImplemented not implemented
	ErrNotImplemented = errors.New("not implemented")
	// ErrMissingWhereClause missing where clause
	ErrMissingWhereClause = errors.New("WHERE conditions required")
	// ErrUnsupportedRelation unsupported relations
	ErrUnsupportedRelation = errors.New("unsupported relations")
	// ErrPtrStructSupported only ptr of struct supported
	ErrPtrStructSupported = errors.New("only ptr of struct supported")
	// ErrorPrimaryKeyRequired primary keys required
	ErrorPrimaryKeyRequired = errors.New("primary key required")
	// ErrorModelValueRequired model value required
	ErrorModelValueRequired = errors.New("model value required")
	// ErrUnsupportedDriver unsupported driver
	ErrUnsupportedDriver = errors.New("unsupported driver")


func Expr

func Expr(expr string, args ...interface{}) clause.Expr

func Scan

func Scan(rows *sql.Rows, db *DB, initialized bool)


type AfterCreateInterface

type AfterCreateInterface interface {
	AfterCreate(*DB) error

type AfterDeleteInterface

type AfterDeleteInterface interface {
	AfterDelete(*DB) error

type AfterFindInterface

type AfterFindInterface interface {
	AfterFind(*DB) error

type AfterSaveInterface

type AfterSaveInterface interface {
	AfterSave(*DB) error

type AfterUpdateInterface

type AfterUpdateInterface interface {
	AfterUpdate(*DB) error

type Association

type Association struct {
	DB           *DB
	Relationship *schema.Relationship
	Error        error

Association Mode contains some helper methods to handle relationship things easily.

func (*Association) Append

func (association *Association) Append(values ...interface{}) error

func (*Association) Clear

func (association *Association) Clear() error

func (*Association) Count

func (association *Association) Count() (count int64)

func (*Association) Delete

func (association *Association) Delete(values ...interface{}) error

func (*Association) Find

func (association *Association) Find(out interface{}, conds ...interface{}) error

func (*Association) Replace

func (association *Association) Replace(values ...interface{}) error

type BeforeCreateInterface

type BeforeCreateInterface interface {
	BeforeCreate(*DB) error

type BeforeDeleteInterface

type BeforeDeleteInterface interface {
	BeforeDelete(*DB) error

type BeforeSaveInterface

type BeforeSaveInterface interface {
	BeforeSave(*DB) error

type BeforeUpdateInterface

type BeforeUpdateInterface interface {
	BeforeUpdate(*DB) error

type Config

type Config struct {
	// GORM perform single create, update, delete operations in transactions by default to ensure database data integrity
	// You can disable it by setting `SkipDefaultTransaction` to true
	SkipDefaultTransaction bool
	// NamingStrategy tables, columns naming strategy
	NamingStrategy schema.Namer
	// Logger
	Logger logger.Interface
	// NowFunc the function to be used when creating a new timestamp
	NowFunc func() time.Time
	// DryRun generate sql without execute
	DryRun bool
	// PrepareStmt executes the given query in cached statement
	PrepareStmt bool
	// DisableAutomaticPing
	DisableAutomaticPing bool

	// ClauseBuilders clause builder
	ClauseBuilders map[string]clause.ClauseBuilder
	// ConnPool db conn pool
	ConnPool ConnPool
	// Dialector database dialector
	// contains filtered or unexported fields

Config GORM config

type ConnPool

type ConnPool interface {
	PrepareContext(ctx context.Context, query string) (*sql.Stmt, error)
	ExecContext(ctx context.Context, query string, args ...interface{}) (sql.Result, error)
	QueryContext(ctx context.Context, query string, args ...interface{}) (*sql.Rows, error)
	QueryRowContext(ctx context.Context, query string, args ...interface{}) *sql.Row

ConnPool db conns pool interface

type ConnPoolBeginner added in v0.2.3

type ConnPoolBeginner interface {
	BeginTx(ctx context.Context, opts *sql.TxOptions) (ConnPool, error)

type DB

type DB struct {
	Error        error
	RowsAffected int64
	Statement    *Statement
	// contains filtered or unexported fields

DB GORM DB definition

func Open

func Open(dialector Dialector, config *Config) (db *DB, err error)

Open initialize db session based on dialector

func (*DB) AddError

func (db *DB) AddError(err error) error

AddError add error to db

func (*DB) Assign

func (db *DB) Assign(attrs ...interface{}) (tx *DB)

func (*DB) Association

func (db *DB) Association(column string) *Association

func (*DB) Attrs

func (db *DB) Attrs(attrs ...interface{}) (tx *DB)

func (*DB) AutoMigrate

func (db *DB) AutoMigrate(dst ...interface{}) error

AutoMigrate run auto migration for given models

func (*DB) Begin

func (db *DB) Begin(opts ...*sql.TxOptions) *DB

Begin begins a transaction

func (*DB) Callback

func (db *DB) Callback() *callbacks

Callback returns callback manager

func (*DB) Clauses

func (db *DB) Clauses(conds ...clause.Expression) (tx *DB)

Clauses Add clauses

func (*DB) Commit

func (db *DB) Commit() *DB

Commit commit a transaction

func (*DB) Count

func (db *DB) Count(count *int64) (tx *DB)

func (*DB) Create

func (db *DB) Create(value interface{}) (tx *DB)

Create insert the value into database

func (*DB) DB added in v0.2.7

func (db *DB) DB() (*sql.DB, error)

DB returns `*sql.DB`

func (*DB) Debug

func (db *DB) Debug() (tx *DB)

Debug start debug mode

func (*DB) Delete

func (db *DB) Delete(value interface{}, conds ...interface{}) (tx *DB)

Delete delete value match given conditions, if the value has primary key, then will including the primary key as condition

func (*DB) Distinct added in v0.2.3

func (db *DB) Distinct(args ...interface{}) (tx *DB)

Distinct specify distinct fields that you want querying

func (*DB) Exec

func (db *DB) Exec(sql string, values ...interface{}) (tx *DB)

Exec execute raw sql

func (*DB) Find

func (db *DB) Find(dest interface{}, conds ...interface{}) (tx *DB)

Find find records that match given conditions

func (*DB) FindInBatches added in v0.2.6

func (db *DB) FindInBatches(dest interface{}, batchSize int, fc func(tx *DB, batch int) error) (tx *DB)

FindInBatches find records in batches

func (*DB) First

func (db *DB) First(dest interface{}, conds ...interface{}) (tx *DB)

First find first record that match given conditions, order by primary key

func (*DB) FirstOrCreate

func (db *DB) FirstOrCreate(dest interface{}, conds ...interface{}) (tx *DB)

func (*DB) FirstOrInit

func (db *DB) FirstOrInit(dest interface{}, conds ...interface{}) (tx *DB)

func (*DB) Get

func (db *DB) Get(key string) (interface{}, bool)

Get get value with key from current db instance's context

func (*DB) Group

func (db *DB) Group(name string) (tx *DB)

Group specify the group method on the find

func (*DB) Having

func (db *DB) Having(query interface{}, args ...interface{}) (tx *DB)

Having specify HAVING conditions for GROUP BY

func (*DB) InstanceGet

func (db *DB) InstanceGet(key string) (interface{}, bool)

InstanceGet get value with key from current db instance's context

func (*DB) InstanceSet

func (db *DB) InstanceSet(key string, value interface{}) *DB

InstanceSet store value with key into current db instance's context

func (*DB) Joins

func (db *DB) Joins(query string, args ...interface{}) (tx *DB)

Joins specify Joins conditions

db.Joins("JOIN emails ON emails.user_id = users.id AND emails.email = ?", "jinzhu@example.org").Find(&user)

func (*DB) Last

func (db *DB) Last(dest interface{}, conds ...interface{}) (tx *DB)

Last find last record that match given conditions, order by primary key

func (*DB) Limit

func (db *DB) Limit(limit int) (tx *DB)

Limit specify the number of records to be retrieved

func (*DB) Migrator

func (db *DB) Migrator() Migrator

Migrator returns migrator

func (*DB) Model

func (db *DB) Model(value interface{}) (tx *DB)

Model specify the model you would like to run db operations

// update all users's name to `hello`
db.Model(&User{}).Update("name", "hello")
// if user's primary key is non-blank, will use it as condition, then will only update the user's name to `hello`
db.Model(&user).Update("name", "hello")

func (*DB) Not

func (db *DB) Not(query interface{}, args ...interface{}) (tx *DB)

Not add NOT conditions

func (*DB) Offset

func (db *DB) Offset(offset int) (tx *DB)

Offset specify the number of records to skip before starting to return the records

func (*DB) Omit

func (db *DB) Omit(columns ...string) (tx *DB)

Omit specify fields that you want to ignore when creating, updating and querying

func (*DB) Or

func (db *DB) Or(query interface{}, args ...interface{}) (tx *DB)

Or add OR conditions

func (*DB) Order

func (db *DB) Order(value interface{}) (tx *DB)

Order specify order when retrieve records from database

db.Order("name DESC")
db.Order(gorm.Expr("name = ? DESC", "first")) // sql expression

func (*DB) Pluck

func (db *DB) Pluck(column string, dest interface{}) (tx *DB)

Pluck used to query single column from a model as a map

var ages []int64
db.Find(&users).Pluck("age", &ages)

func (*DB) Preload

func (db *DB) Preload(query string, args ...interface{}) (tx *DB)

Preload preload associations with given conditions

db.Preload("Orders", "state NOT IN (?)", "cancelled").Find(&users)

func (*DB) Raw

func (db *DB) Raw(sql string, values ...interface{}) (tx *DB)

func (*DB) Rollback

func (db *DB) Rollback() *DB

Rollback rollback a transaction

func (*DB) RollbackTo added in v0.2.9

func (db *DB) RollbackTo(name string) *DB

func (*DB) Row

func (db *DB) Row() *sql.Row

func (*DB) Rows

func (db *DB) Rows() (*sql.Rows, error)

func (*DB) Save

func (db *DB) Save(value interface{}) (tx *DB)

Save update value in database, if the value doesn't have primary key, will insert it

func (*DB) SavePoint added in v0.2.9

func (db *DB) SavePoint(name string) *DB

func (*DB) Scan

func (db *DB) Scan(dest interface{}) (tx *DB)

Scan scan value to a struct

func (*DB) ScanRows

func (db *DB) ScanRows(rows *sql.Rows, dest interface{}) error

func (*DB) Scopes

func (db *DB) Scopes(funcs ...func(*DB) *DB) *DB

Scopes pass current database connection to arguments `func(DB) DB`, which could be used to add conditions dynamically

func AmountGreaterThan1000(db *gorm.DB) *gorm.DB {
    return db.Where("amount > ?", 1000)

func OrderStatus(status []string) func (db *gorm.DB) *gorm.DB {
    return func (db *gorm.DB) *gorm.DB {
        return db.Scopes(AmountGreaterThan1000).Where("status in (?)", status)

db.Scopes(AmountGreaterThan1000, OrderStatus([]string{"paid", "shipped"})).Find(&orders)

func (*DB) Select

func (db *DB) Select(query interface{}, args ...interface{}) (tx *DB)

Select specify fields that you want when querying, creating, updating

func (*DB) Session

func (db *DB) Session(config *Session) *DB

Session create new db session

func (*DB) Set

func (db *DB) Set(key string, value interface{}) *DB

Set store value with key into current db instance's context

func (*DB) SetupJoinTable

func (db *DB) SetupJoinTable(model interface{}, field string, joinTable interface{}) error

func (*DB) Table

func (db *DB) Table(name string) (tx *DB)

Table specify the table you would like to run db operations

func (*DB) Take

func (db *DB) Take(dest interface{}, conds ...interface{}) (tx *DB)

Take return a record that match given conditions, the order will depend on the database implementation

func (*DB) Transaction

func (db *DB) Transaction(fc func(tx *DB) error, opts ...*sql.TxOptions) (err error)

Transaction start a transaction as a block, return error will rollback, otherwise to commit.

func (*DB) Unscoped

func (db *DB) Unscoped() (tx *DB)

func (*DB) Update

func (db *DB) Update(column string, value interface{}) (tx *DB)

Update update attributes with callbacks, refer: https://gorm.io/docs/update.html#Update-Changed-Fields

func (*DB) UpdateColumn

func (db *DB) UpdateColumn(column string, value interface{}) (tx *DB)

func (*DB) UpdateColumns

func (db *DB) UpdateColumns(values interface{}) (tx *DB)

func (*DB) Updates

func (db *DB) Updates(values interface{}) (tx *DB)

Updates update attributes with callbacks, refer: https://gorm.io/docs/update.html#Update-Changed-Fields

func (*DB) Where

func (db *DB) Where(query interface{}, args ...interface{}) (tx *DB)

Where add conditions

func (*DB) WithContext

func (db *DB) WithContext(ctx context.Context) *DB

WithContext change current instance db's context to ctx

type DeletedAt

type DeletedAt sql.NullTime

func (DeletedAt) DeleteClauses

func (DeletedAt) DeleteClauses() []clause.Interface

func (DeletedAt) QueryClauses

func (DeletedAt) QueryClauses() []clause.Interface

func (*DeletedAt) Scan

func (n *DeletedAt) Scan(value interface{}) error

Scan implements the Scanner interface.

func (DeletedAt) Value

func (n DeletedAt) Value() (driver.Value, error)

Value implements the driver Valuer interface.

type Dialector

type Dialector interface {
	Name() string
	Initialize(*DB) error
	Migrator(db *DB) Migrator
	DataTypeOf(*schema.Field) string
	DefaultValueOf(*schema.Field) clause.Expression
	BindVarTo(writer clause.Writer, stmt *Statement, v interface{})
	QuoteTo(clause.Writer, string)
	Explain(sql string, vars ...interface{}) string

Dialector GORM database dialector

type Migrator

type Migrator interface {
	// AutoMigrate
	AutoMigrate(dst ...interface{}) error

	// Database
	CurrentDatabase() string

	// Tables
	CreateTable(dst ...interface{}) error
	DropTable(dst ...interface{}) error
	HasTable(dst interface{}) bool
	RenameTable(oldName, newName interface{}) error

	// Columns
	AddColumn(dst interface{}, field string) error
	DropColumn(dst interface{}, field string) error
	AlterColumn(dst interface{}, field string) error
	HasColumn(dst interface{}, field string) bool
	RenameColumn(dst interface{}, oldName, field string) error
	ColumnTypes(dst interface{}) ([]*sql.ColumnType, error)

	// Views
	CreateView(name string, option ViewOption) error
	DropView(name string) error

	// Constraints
	CreateConstraint(dst interface{}, name string) error
	DropConstraint(dst interface{}, name string) error
	HasConstraint(dst interface{}, name string) bool

	// Indexes
	CreateIndex(dst interface{}, name string) error
	DropIndex(dst interface{}, name string) error
	HasIndex(dst interface{}, name string) bool
	RenameIndex(dst interface{}, oldName, newName string) error

type Model

type Model struct {
	ID        uint `gorm:"primarykey"`
	CreatedAt time.Time
	UpdatedAt time.Time
	DeletedAt DeletedAt `gorm:"index"`

Model a basic GoLang struct which includes the following fields: ID, CreatedAt, UpdatedAt, DeletedAt It may be embedded into your model or you may build your own model without it

type User struct {

type PreparedStmtDB added in v0.2.3

type PreparedStmtDB struct {
	// contains filtered or unexported fields

func (*PreparedStmtDB) BeginTx added in v0.2.3

func (db *PreparedStmtDB) BeginTx(ctx context.Context, opt *sql.TxOptions) (ConnPool, error)

func (*PreparedStmtDB) ExecContext added in v0.2.3

func (db *PreparedStmtDB) ExecContext(ctx context.Context, query string, args ...interface{}) (sql.Result, error)

func (*PreparedStmtDB) QueryContext added in v0.2.3

func (db *PreparedStmtDB) QueryContext(ctx context.Context, query string, args ...interface{}) (*sql.Rows, error)

func (*PreparedStmtDB) QueryRowContext added in v0.2.3

func (db *PreparedStmtDB) QueryRowContext(ctx context.Context, query string, args ...interface{}) *sql.Row

type PreparedStmtTX added in v0.2.3

type PreparedStmtTX struct {
	PreparedStmtDB *PreparedStmtDB

func (*PreparedStmtTX) ExecContext added in v0.2.3

func (tx *PreparedStmtTX) ExecContext(ctx context.Context, query string, args ...interface{}) (sql.Result, error)

func (*PreparedStmtTX) QueryContext added in v0.2.3

func (tx *PreparedStmtTX) QueryContext(ctx context.Context, query string, args ...interface{}) (*sql.Rows, error)

func (*PreparedStmtTX) QueryRowContext added in v0.2.3

func (tx *PreparedStmtTX) QueryRowContext(ctx context.Context, query string, args ...interface{}) *sql.Row

type SavePointerDialectorInterface added in v0.2.9

type SavePointerDialectorInterface interface {
	SavePoint(tx *DB, name string) error
	RollbackTo(tx *DB, name string) error

type Session

type Session struct {
	DryRun         bool
	PrepareStmt    bool
	WithConditions bool
	Context        context.Context
	Logger         logger.Interface
	NowFunc        func() time.Time

Session session config when create session with Session() method

type SoftDeleteClause

type SoftDeleteClause struct {

func (SoftDeleteClause) Build

func (SoftDeleteClause) MergeClause

func (SoftDeleteClause) MergeClause(*clause.Clause)

func (SoftDeleteClause) ModifyStatement

func (SoftDeleteClause) ModifyStatement(stmt *Statement)

func (SoftDeleteClause) Name

func (SoftDeleteClause) Name() string

type Statement

type Statement struct {
	Table                string
	Model                interface{}
	Unscoped             bool
	Dest                 interface{}
	ReflectValue         reflect.Value
	Clauses              map[string]clause.Clause
	Distinct             bool
	Selects              []string // selected columns
	Omits                []string // omit columns
	Joins                map[string][]interface{}
	Preloads             map[string][]interface{}
	Settings             sync.Map
	ConnPool             ConnPool
	Schema               *schema.Schema
	Context              context.Context
	RaiseErrorOnNotFound bool
	UpdatingColumn       bool
	SQL                  strings.Builder
	Vars                 []interface{}
	NamedVars            []sql.NamedArg
	// contains filtered or unexported fields

Statement statement

func (*Statement) AddClause

func (stmt *Statement) AddClause(v clause.Interface)

AddClause add clause

func (*Statement) AddClauseIfNotExists

func (stmt *Statement) AddClauseIfNotExists(v clause.Interface)

AddClauseIfNotExists add clause if not exists

func (*Statement) AddVar

func (stmt *Statement) AddVar(writer clause.Writer, vars ...interface{})

Write write string

func (*Statement) Build

func (stmt *Statement) Build(clauses ...string)

Build build sql with clauses names

func (*Statement) BuildCondition added in v0.2.5

func (stmt *Statement) BuildCondition(query interface{}, args ...interface{}) (conds []clause.Expression)

BuildCondition build condition

func (*Statement) Parse

func (stmt *Statement) Parse(value interface{}) (err error)

func (*Statement) Quote

func (stmt *Statement) Quote(field interface{}) string

Quote returns quoted value

func (*Statement) QuoteTo

func (stmt *Statement) QuoteTo(writer clause.Writer, field interface{})

QuoteTo write quoted value to writer

func (*Statement) WriteByte

func (stmt *Statement) WriteByte(c byte) error

Write write string

func (*Statement) WriteQuoted

func (stmt *Statement) WriteQuoted(value interface{}) error

WriteQuoted write quoted value

func (*Statement) WriteString

func (stmt *Statement) WriteString(str string) (int, error)

Write write string

type StatementModifier

type StatementModifier interface {

StatementModifier statement modifier interface

type TxBeginner

type TxBeginner interface {
	BeginTx(ctx context.Context, opts *sql.TxOptions) (*sql.Tx, error)

type TxCommitter added in v0.2.3

type TxCommitter interface {
	Commit() error
	Rollback() error

type ViewOption

type ViewOption struct {
	Replace     bool
	CheckOption string
	Query       *DB

ViewOption view option


Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL