Back to

Package gorm

Latest Go to latest

The latest major version is .

Published: 4 days ago | License: MIT | Module:



var (
	// ErrRecordNotFound record not found error
	ErrRecordNotFound = errors.New("record not found")
	// ErrInvalidTransaction invalid transaction when you are trying to `Commit` or `Rollback`
	ErrInvalidTransaction = errors.New("no valid transaction")
	// 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")
	// ErrPrimaryKeyRequired primary keys required
	ErrPrimaryKeyRequired = errors.New("primary key required")
	// ErrModelValueRequired model value required
	ErrModelValueRequired = errors.New("model value required")
	// ErrInvalidData unsupported data
	ErrInvalidData = errors.New("unsupported data")
	// ErrUnsupportedDriver unsupported driver
	ErrUnsupportedDriver = errors.New("unsupported driver")
	// ErrRegistered registered
	ErrRegistered = errors.New("registered")
	// ErrInvalidField invalid field
	ErrInvalidField = errors.New("invalid field")
	// ErrEmptySlice empty slice found
	ErrEmptySlice = errors.New("empty slice found")
	// ErrDryRunModeUnsupported dry run mode unsupported
	ErrDryRunModeUnsupported = errors.New("dry run mode unsupported")

func Expr

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

func Scan

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

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 ColumnType

type ColumnType interface {
	Name() string
	DatabaseTypeName() string
	Length() (length int64, ok bool)
	DecimalSize() (precision int64, scale int64, ok bool)
	Nullable() (nullable bool, ok bool)

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
	// FullSaveAssociations full save associations
	FullSaveAssociations bool
	// 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
	// DisableForeignKeyConstraintWhenMigrating
	DisableForeignKeyConstraintWhenMigrating bool
	// AllowGlobalUpdate allow global update
	AllowGlobalUpdate bool

	// ClauseBuilders clause builder
	ClauseBuilders map[string]clause.ClauseBuilder
	// ConnPool db conn pool
	ConnPool ConnPool
	// Dialector database dialector
	// Plugins registered plugins
	Plugins map[string]Plugin
	// 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

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

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

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

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 = AND = ?", "").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(clause.OrderByColumn{Column: clause.Column{Name: "name"}, Desc: true})

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

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

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, args ...interface{}) (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:

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:

func (*DB) Use

func (db *DB) Use(plugin Plugin) (err error)

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(f *schema.Field) []clause.Interface

func (DeletedAt) MarshalJSON

func (n DeletedAt) MarshalJSON() ([]byte, error)

func (DeletedAt) QueryClauses

func (DeletedAt) QueryClauses(f *schema.Field) []clause.Interface

func (*DeletedAt) Scan

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

Scan implements the Scanner interface.

func (*DeletedAt) UnmarshalJSON

func (n *DeletedAt) UnmarshalJSON(b []byte) error

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
	FullDataTypeOf(*schema.Field) clause.Expr

	// 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
	MigrateColumn(dst interface{}, field *schema.Field, columnType ColumnType) error
	HasColumn(dst interface{}, field string) bool
	RenameColumn(dst interface{}, oldName, field string) error
	ColumnTypes(dst interface{}) ([]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 Plugin

type Plugin interface {
	Name() string
	Initialize(*DB) error

Plugin GORM plugin interface

type PreparedStmtDB

type PreparedStmtDB struct {
	Stmts       map[string]*sql.Stmt
	PreparedSQL []string
	Mux         *sync.RWMutex

func (*PreparedStmtDB) BeginTx

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

func (*PreparedStmtDB) Close

func (db *PreparedStmtDB) Close()

func (*PreparedStmtDB) ExecContext

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

func (*PreparedStmtDB) QueryContext

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

func (*PreparedStmtDB) QueryRowContext

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

type PreparedStmtTX

type PreparedStmtTX struct {
	PreparedStmtDB *PreparedStmtDB

func (*PreparedStmtTX) Commit

func (tx *PreparedStmtTX) Commit() error

func (*PreparedStmtTX) ExecContext

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

func (*PreparedStmtTX) QueryContext

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

func (*PreparedStmtTX) QueryRowContext

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

func (*PreparedStmtTX) Rollback

func (tx *PreparedStmtTX) Rollback() error

type SavePointerDialectorInterface

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

SavePointerDialectorInterface save pointer interface

type Session

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

Session session config when create session with Session() method

type SoftDeleteDeleteClause

type SoftDeleteDeleteClause struct {
	Field *schema.Field

func (SoftDeleteDeleteClause) Build

func (sd SoftDeleteDeleteClause) Build(clause.Builder)

func (SoftDeleteDeleteClause) MergeClause

func (sd SoftDeleteDeleteClause) MergeClause(*clause.Clause)

func (SoftDeleteDeleteClause) ModifyStatement

func (sd SoftDeleteDeleteClause) ModifyStatement(stmt *Statement)

func (SoftDeleteDeleteClause) Name

func (sd SoftDeleteDeleteClause) Name() string

type SoftDeleteQueryClause

type SoftDeleteQueryClause struct {
	Field *schema.Field

func (SoftDeleteQueryClause) Build

func (sd SoftDeleteQueryClause) Build(clause.Builder)

func (SoftDeleteQueryClause) MergeClause

func (sd SoftDeleteQueryClause) MergeClause(*clause.Clause)

func (SoftDeleteQueryClause) ModifyStatement

func (sd SoftDeleteQueryClause) ModifyStatement(stmt *Statement)

func (SoftDeleteQueryClause) Name

func (sd SoftDeleteQueryClause) Name() string

type Statement

type Statement struct {
	TableExpr            *clause.Expr
	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                []join
	Preloads             map[string][]interface{}
	Settings             sync.Map
	ConnPool             ConnPool
	Schema               *schema.Schema
	Context              context.Context
	RaiseErrorOnNotFound bool
	UpdatingColumn       bool
	SQL                  strings.Builder
	Vars                 []interface{}
	CurDestIndex         int
	// 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

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

BuildCondition build condition

func (*Statement) Changed

func (stmt *Statement) Changed(fields ...string) bool

Changed check model changed or not when updating

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) SelectAndOmitColumns

func (stmt *Statement) SelectAndOmitColumns(requireCreate, requireUpdate bool) (map[string]bool, bool)

SelectAndOmitColumns get select and omit columns, select -> true, omit -> false

func (*Statement) SetColumn

func (stmt *Statement) SetColumn(name string, value interface{})

Helpers SetColumn set column's value

func (*Statement) WriteByte

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

Write write string

func (*Statement) WriteQuoted

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

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

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

type Valuer

type Valuer interface {
	GormValue(context.Context, *DB) clause.Expr

Valuer gorm valuer interface

type ViewOption

type ViewOption struct {
	Replace     bool
	CheckOption string
	Query       *DB

ViewOption view option

Package Files

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier