gorm

package module
v0.2.6 Latest Latest
Warning

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

 Go to latest Published: Jun 14, 2020 License: MIT Imports: 14 Imported by: 58,029

README

GORM

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

Overview

  • 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

Contributing

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

License

© Jinzhu, 2013~time.Now

Released under the MIT License

Documentation

Index

Constants

This section is empty.

Variables

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

Functions

func Expr 

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

func Scan 

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

Types

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
	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 {
	*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) 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("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(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) 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) 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://jinzhu.github.io/gorm/crud.html#update

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://jinzhu.github.io/gorm/crud.html#update

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
	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 {
  gorm.Model
}

type PreparedStmtDB added in v0.2.3 

type PreparedStmtDB struct {
	ConnPool
	// 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 {
	*sql.Tx
	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 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) Build(clause.Builder)

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

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

Source Files

View all Source files

Directories

Path Synopsis
tests

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.