Back to godoc.org
gorm.io/gorm

Package gorm

v1.20.5
Latest Go to latest

The latest major version is .

Published: 4 days ago | License: MIT | Module: gorm.io/gorm

Index

Variables

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
	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 {
	*Config
	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("Account").Find(&user)
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(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: 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) 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 {
  gorm.Model
}

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
	ConnPool
}

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 {
	*sql.Tx
	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 {
	*DB
	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 {
	ModifyStatement(*Statement)
}

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