orm

package
Version: v9.2.1 Latest Latest
Warning

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

Go to latest
Published: Apr 22, 2021 License: BSD-2-Clause Imports: 25 Imported by: 105

Documentation

Index

Constants

View Source
const (
	PrimaryKeyFlag = uint8(1) << iota
	ForeignKeyFlag
	NotNullFlag
	UseZeroFlag
	UniqueFlag
	ArrayFlag
)
View Source
const (
	HasOneRelation = 1 << iota
	BelongsToRelation
	HasManyRelation
	Many2ManyRelation
)

Variables

This section is empty.

Functions

func CreateComposite

func CreateComposite(db DB, model interface{}, opt *CreateCompositeOptions) error

func CreateTable

func CreateTable(db DB, model interface{}, opt *CreateTableOptions) error

func Delete

func Delete(db DB, model interface{}) error

Delete deletes a given model from the db

func DropComposite

func DropComposite(db DB, model interface{}, opt *DropCompositeOptions) error

func DropTable

func DropTable(db DB, model interface{}, opt *DropTableOptions) error

func ForceDelete

func ForceDelete(db DB, model interface{}) error

ForceDelete force deletes a given model from the db

func Insert

func Insert(db DB, model ...interface{}) error

func OnUpdate

func OnUpdate(fks []*Field) string

func RegisterTable

func RegisterTable(strct interface{})

RegisterTable registers a struct as SQL table. It is usually used to register intermediate table in many to many relationship.

func Scan

func Scan(values ...interface{}) scanValuesModel

nolint

func Select

func Select(db DB, model interface{}) error

func SetTableNameInflector

func SetTableNameInflector(fn func(string) string)

SetTableNameInflector overrides the default func that pluralizes model name to get table name, e.g. my_article becomes my_articles.

func Update

func Update(db DB, model interface{}) error

Types

type AfterDeleteHook

type AfterDeleteHook interface {
	AfterDelete(context.Context) error
}

type AfterInsertHook

type AfterInsertHook interface {
	AfterInsert(context.Context) error
}

type AfterScanHook

type AfterScanHook interface {
	AfterScan(context.Context) error
}

type AfterSelectHook

type AfterSelectHook interface {
	AfterSelect(context.Context) error
}

type AfterUpdateHook

type AfterUpdateHook interface {
	AfterUpdate(context.Context) error
}

type BeforeDeleteHook

type BeforeDeleteHook interface {
	BeforeDelete(context.Context) (context.Context, error)
}

type BeforeInsertHook

type BeforeInsertHook interface {
	BeforeInsert(context.Context) (context.Context, error)
}

type BeforeScanHook added in v9.0.4

type BeforeScanHook interface {
	BeforeScan(context.Context) error
}

type BeforeUpdateHook

type BeforeUpdateHook interface {
	BeforeUpdate(context.Context) (context.Context, error)
}

type ColumnScanner

type ColumnScanner interface {
	// Scan assigns a column value from a row.
	//
	// An error should be returned if the value can not be stored
	// without loss of information.
	ScanColumn(colIdx int, colName string, rd types.Reader, n int) error
}

ColumnScanner is used to scan column values.

type CreateCompositeOptions

type CreateCompositeOptions struct {
	Varchar int // replaces PostgreSQL data type `text` with `varchar(n)`
}

type CreateTableOptions

type CreateTableOptions struct {
	Varchar     int // replaces PostgreSQL data type `text` with `varchar(n)`
	Temp        bool
	IfNotExists bool

	// FKConstraints causes CreateTable to create foreign key constraints
	// for has one relations. ON DELETE hook can be added using tag
	// `pg:"on_delete:RESTRICT"` on foreign key field. ON UPDATE hook can be added using tag
	// `pg:"on_update:CASCADE"`
	FKConstraints bool
}

type DB

type DB interface {
	Model(model ...interface{}) *Query
	ModelContext(c context.Context, model ...interface{}) *Query
	Select(model interface{}) error
	Insert(model ...interface{}) error
	Update(model interface{}) error
	Delete(model interface{}) error
	ForceDelete(model interface{}) error

	Exec(query interface{}, params ...interface{}) (Result, error)
	ExecContext(c context.Context, query interface{}, params ...interface{}) (Result, error)
	ExecOne(query interface{}, params ...interface{}) (Result, error)
	ExecOneContext(c context.Context, query interface{}, params ...interface{}) (Result, error)
	Query(model, query interface{}, params ...interface{}) (Result, error)
	QueryContext(c context.Context, model, query interface{}, params ...interface{}) (Result, error)
	QueryOne(model, query interface{}, params ...interface{}) (Result, error)
	QueryOneContext(c context.Context, model, query interface{}, params ...interface{}) (Result, error)

	CopyFrom(r io.Reader, query interface{}, params ...interface{}) (Result, error)
	CopyTo(w io.Writer, query interface{}, params ...interface{}) (Result, error)

	Context() context.Context
	Formatter() QueryFormatter
}

DB is a common interface for pg.DB and pg.Tx types.

type Discard

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

func (Discard) AddColumnScanner

func (m Discard) AddColumnScanner(ColumnScanner) error

func (Discard) AfterDelete

func (Discard) AfterDelete(c context.Context) error

func (Discard) AfterInsert

func (Discard) AfterInsert(c context.Context) error

func (Discard) AfterSelect

func (Discard) AfterSelect(c context.Context) error

func (Discard) AfterUpdate

func (Discard) AfterUpdate(c context.Context) error

func (Discard) BeforeDelete

func (Discard) BeforeDelete(c context.Context) (context.Context, error)

func (Discard) BeforeInsert

func (Discard) BeforeInsert(c context.Context) (context.Context, error)

func (Discard) BeforeUpdate

func (Discard) BeforeUpdate(c context.Context) (context.Context, error)

func (Discard) Init

func (Discard) Init() error

func (Discard) NextColumnScanner

func (m Discard) NextColumnScanner() ColumnScanner

func (Discard) ScanColumn

func (m Discard) ScanColumn(colIdx int, colName string, rd types.Reader, n int) error

type DropCompositeOptions

type DropCompositeOptions struct {
	IfExists bool
	Cascade  bool
}

type DropTableOptions

type DropTableOptions struct {
	IfExists bool
	Cascade  bool
}

type Field

type Field struct {
	Field reflect.StructField
	Type  reflect.Type
	Index []int

	GoName      string     // struct field name, e.g. Id
	SQLName     string     // SQL name, .e.g. id
	Column      types.Safe // escaped SQL name, e.g. "id"
	SQLType     string
	UserSQLType string
	Default     types.Safe
	OnDelete    string
	OnUpdate    string
	// contains filtered or unexported fields
}

func (*Field) AppendValue

func (f *Field) AppendValue(b []byte, strct reflect.Value, quote int) []byte

func (*Field) Clone

func (f *Field) Clone() *Field

func (*Field) HasZeroValue

func (f *Field) HasZeroValue(strct reflect.Value) bool

func (*Field) NullZero

func (f *Field) NullZero() bool

func (*Field) ScanValue

func (f *Field) ScanValue(strct reflect.Value, rd types.Reader, n int) error

func (*Field) Value

func (f *Field) Value(strct reflect.Value) reflect.Value

type Formatter

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

func NewFormatter

func NewFormatter() *Formatter

func (*Formatter) FormatQuery

func (f *Formatter) FormatQuery(dst []byte, query string, params ...interface{}) []byte

func (*Formatter) FormatQueryBytes

func (f *Formatter) FormatQueryBytes(dst, query []byte, params ...interface{}) []byte

func (*Formatter) Param

func (f *Formatter) Param(param string) interface{}

func (*Formatter) String

func (f *Formatter) String() string

func (*Formatter) WithModel

func (f *Formatter) WithModel(model interface{}) *Formatter

func (*Formatter) WithParam

func (f *Formatter) WithParam(param string, value interface{}) *Formatter

func (*Formatter) WithTableModel

func (f *Formatter) WithTableModel(model TableModel) *Formatter

type HooklessModel

type HooklessModel interface {
	// Init is responsible to initialize/reset model state.
	// It is called only once no matter how many rows were returned.
	Init() error

	// NextColumnScanner returns a ColumnScanner that is used to scan columns
	// from the current row. It is called once for every row.
	NextColumnScanner() ColumnScanner

	// AddColumnScanner adds the ColumnScanner to the model.
	AddColumnScanner(ColumnScanner) error
}

type Method

type Method struct {
	Index int
	// contains filtered or unexported fields
}

func (*Method) AppendValue

func (m *Method) AppendValue(dst []byte, strct reflect.Value, quote int) []byte

func (*Method) Has

func (m *Method) Has(flag int8) bool

func (*Method) Value

func (m *Method) Value(strct reflect.Value) reflect.Value

type Query

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

func NewQuery

func NewQuery(db DB, model ...interface{}) *Query

func NewQueryContext

func NewQueryContext(c context.Context, db DB, model ...interface{}) *Query

func (*Query) AllWithDeleted

func (q *Query) AllWithDeleted() *Query

AllWithDeleted changes query to return all rows including soft deleted ones.

func (*Query) AppendQuery

func (q *Query) AppendQuery(fmter QueryFormatter, b []byte) ([]byte, error)

func (*Query) Apply

func (q *Query) Apply(fn func(*Query) (*Query, error)) *Query

Apply calls the fn passing the Query as an argument.

func (*Query) Clone

func (q *Query) Clone() *Query

Clone clones the Query.

func (*Query) Column

func (q *Query) Column(columns ...string) *Query

Column adds a column to the Query quoting it according to PostgreSQL rules. Does not expand params like ?TableAlias etc. ColumnExpr can be used to bypass quoting restriction or for params expansion. Column name can be:

- column_name,
- table_alias.column_name,
- table_alias.*.

func (*Query) ColumnExpr

func (q *Query) ColumnExpr(expr string, params ...interface{}) *Query

ColumnExpr adds column expression to the Query.

func (*Query) Context

func (q *Query) Context(c context.Context) *Query

func (*Query) CopyFrom

func (q *Query) CopyFrom(r io.Reader, query interface{}, params ...interface{}) (Result, error)

CopyFrom is an alias from DB.CopyFrom.

func (*Query) CopyTo

func (q *Query) CopyTo(w io.Writer, query interface{}, params ...interface{}) (Result, error)

CopyTo is an alias from DB.CopyTo.

func (*Query) Count

func (q *Query) Count() (int, error)

Count returns number of rows matching the query using count aggregate function.

func (*Query) CountEstimate

func (q *Query) CountEstimate(threshold int) (int, error)

CountEstimate uses EXPLAIN to get estimated number of rows returned the query. If that number is bigger than the threshold it returns the estimation. Otherwise it executes another query using count aggregate function and returns the result.

Based on https://wiki.postgresql.org/wiki/Count_estimate

func (*Query) CreateTable

func (q *Query) CreateTable(opt *CreateTableOptions) error

func (*Query) DB

func (q *Query) DB(db DB) *Query

func (*Query) Delete

func (q *Query) Delete(values ...interface{}) (Result, error)

Delete deletes the model. When model has deleted_at column the row is soft deleted instead.

func (*Query) Deleted

func (q *Query) Deleted() *Query

Deleted adds `WHERE deleted_at IS NOT NULL` clause for soft deleted models.

func (*Query) Distinct

func (q *Query) Distinct() *Query

func (*Query) DistinctOn

func (q *Query) DistinctOn(expr string, params ...interface{}) *Query

func (*Query) DropTable

func (q *Query) DropTable(opt *DropTableOptions) error

func (*Query) Except

func (q *Query) Except(other *Query) *Query

func (*Query) ExceptAll

func (q *Query) ExceptAll(other *Query) *Query

func (*Query) ExcludeColumn

func (q *Query) ExcludeColumn(columns ...string) *Query

ExcludeColumn excludes a column from the list of to be selected columns.

func (*Query) Exec

func (q *Query) Exec(query interface{}, params ...interface{}) (Result, error)

Exec is an alias for DB.Exec.

func (*Query) ExecOne

func (q *Query) ExecOne(query interface{}, params ...interface{}) (Result, error)

ExecOne is an alias for DB.ExecOne.

func (*Query) Exists

func (q *Query) Exists() (bool, error)

Exists returns true or false depending if there are any rows matching the query.

func (*Query) First

func (q *Query) First() error

First sorts rows by primary key and selects the first row. It is a shortcut for:

q.OrderExpr("id ASC").Limit(1)

func (*Query) For

func (q *Query) For(s string, params ...interface{}) *Query

func (*Query) ForEach

func (q *Query) ForEach(fn interface{}) error

ForEach calls the function for each row returned by the query without loading all rows into the memory.

Function can accept a struct, a pointer to a struct, an orm.Model, or values for the columns in a row. Function must return an error.

func (*Query) ForceDelete

func (q *Query) ForceDelete(values ...interface{}) (Result, error)

Delete forces delete of the model with deleted_at column.

func (*Query) Group

func (q *Query) Group(columns ...string) *Query

func (*Query) GroupExpr

func (q *Query) GroupExpr(group string, params ...interface{}) *Query

func (*Query) Having

func (q *Query) Having(having string, params ...interface{}) *Query

func (*Query) Insert

func (q *Query) Insert(values ...interface{}) (Result, error)

Insert inserts the model.

func (*Query) Intersect

func (q *Query) Intersect(other *Query) *Query

func (*Query) IntersectAll

func (q *Query) IntersectAll(other *Query) *Query

func (*Query) Join

func (q *Query) Join(join string, params ...interface{}) *Query

func (*Query) JoinOn

func (q *Query) JoinOn(condition string, params ...interface{}) *Query

JoinOn appends join condition to the last join.

func (*Query) JoinOnOr

func (q *Query) JoinOnOr(condition string, params ...interface{}) *Query

func (*Query) Last

func (q *Query) Last() error

Last sorts rows by primary key and selects the last row. It is a shortcut for:

q.OrderExpr("id DESC").Limit(1)

func (*Query) Limit

func (q *Query) Limit(n int) *Query

func (*Query) Model

func (q *Query) Model(model ...interface{}) *Query

func (*Query) New

func (q *Query) New() *Query

New returns new zero Query binded to the current db.

func (*Query) Offset

func (q *Query) Offset(n int) *Query

func (*Query) OnConflict

func (q *Query) OnConflict(s string, params ...interface{}) *Query

func (*Query) Order

func (q *Query) Order(orders ...string) *Query

Order adds sort order to the Query quoting column name. Does not expand params like ?TableAlias etc. OrderExpr can be used to bypass quoting restriction or for params expansion.

func (*Query) OrderExpr

func (q *Query) OrderExpr(order string, params ...interface{}) *Query

Order adds sort order to the Query.

func (*Query) Query

func (q *Query) Query(model, query interface{}, params ...interface{}) (Result, error)

Query is an alias for DB.Query.

func (*Query) QueryOne

func (q *Query) QueryOne(model, query interface{}, params ...interface{}) (Result, error)

QueryOne is an alias for DB.QueryOne.

func (*Query) Relation

func (q *Query) Relation(name string, apply ...func(*Query) (*Query, error)) *Query

Relation adds a relation to the query. Relation name can be:

- RelationName to select all columns,
- RelationName.column_name,
- RelationName._ to join relation without selecting relation columns.

func (*Query) Returning

func (q *Query) Returning(s string, params ...interface{}) *Query

Returning adds a RETURNING clause to the query.

`Returning("NULL")` can be used to suppress default returning clause generated by go-pg for INSERT queries to get values for null columns.

func (*Query) Select

func (q *Query) Select(values ...interface{}) error

Select selects the model.

func (*Query) SelectAndCount

func (q *Query) SelectAndCount(values ...interface{}) (count int, firstErr error)

SelectAndCount runs Select and Count in two goroutines, waits for them to finish and returns the result. If query limit is -1 it does not select any data and only counts the results.

func (*Query) SelectAndCountEstimate

func (q *Query) SelectAndCountEstimate(threshold int, values ...interface{}) (count int, firstErr error)

SelectAndCountEstimate runs Select and CountEstimate in two goroutines, waits for them to finish and returns the result. If query limit is -1 it does not select any data and only counts the results.

func (*Query) SelectOrInsert

func (q *Query) SelectOrInsert(values ...interface{}) (inserted bool, _ error)

SelectOrInsert selects the model inserting one if it does not exist. It returns true when model was inserted.

func (*Query) Set

func (q *Query) Set(set string, params ...interface{}) *Query

func (*Query) Table

func (q *Query) Table(tables ...string) *Query

func (*Query) TableExpr

func (q *Query) TableExpr(expr string, params ...interface{}) *Query

func (*Query) TableModel

func (q *Query) TableModel() TableModel

func (*Query) Union

func (q *Query) Union(other *Query) *Query

func (*Query) UnionAll

func (q *Query) UnionAll(other *Query) *Query

func (*Query) Update

func (q *Query) Update(scan ...interface{}) (Result, error)

Update updates the model.

func (*Query) UpdateNotZero

func (q *Query) UpdateNotZero(scan ...interface{}) (Result, error)

Update updates the model omitting fields with zero values such as:

- empty string,
- 0,
- zero time,
- empty map or slice,
- byte array with all zeroes,
- nil ptr,
- types with method `IsZero() == true`.

func (*Query) Value

func (q *Query) Value(column string, value string, params ...interface{}) *Query

Value overwrites model value for the column in INSERT and UPDATE queries.

func (*Query) Where

func (q *Query) Where(condition string, params ...interface{}) *Query

func (*Query) WhereGroup

func (q *Query) WhereGroup(fn func(*Query) (*Query, error)) *Query

WhereGroup encloses conditions added in the function in parentheses.

q.Where("TRUE").
	WhereGroup(func(q *orm.Query) (*orm.Query, error) {
		q = q.WhereOr("FALSE").WhereOr("TRUE").
		return q, nil
	})

generates

WHERE TRUE AND (FALSE OR TRUE)

func (*Query) WhereIn

func (q *Query) WhereIn(where string, slice interface{}) *Query

WhereIn is a shortcut for Where and pg.In:

func (*Query) WhereInMulti

func (q *Query) WhereInMulti(where string, values ...interface{}) *Query

WhereInMulti is a shortcut for Where and pg.InMulti:

func (*Query) WhereNotGroup

func (q *Query) WhereNotGroup(fn func(*Query) (*Query, error)) *Query

WhereGroup encloses conditions added in the function in parentheses.

q.Where("TRUE").
	WhereNotGroup(func(q *orm.Query) (*orm.Query, error) {
		q = q.WhereOr("FALSE").WhereOr("TRUE").
		return q, nil
	})

generates

WHERE TRUE AND NOT (FALSE OR TRUE)

func (*Query) WhereOr

func (q *Query) WhereOr(condition string, params ...interface{}) *Query

func (*Query) WhereOrGroup

func (q *Query) WhereOrGroup(fn func(*Query) (*Query, error)) *Query

WhereOrGroup encloses conditions added in the function in parentheses.

q.Where("TRUE").
	WhereOrGroup(func(q *orm.Query) (*orm.Query, error) {
		q = q.Where("FALSE").Where("TRUE").
		return q, nil
	})

generates

WHERE TRUE OR (FALSE AND TRUE)

func (*Query) WhereOrNotGroup

func (q *Query) WhereOrNotGroup(fn func(*Query) (*Query, error)) *Query

WhereOrGroup encloses conditions added in the function in parentheses.

q.Where("TRUE").
	WhereOrGroup(func(q *orm.Query) (*orm.Query, error) {
		q = q.Where("FALSE").Where("TRUE").
		return q, nil
	})

generates

WHERE TRUE OR NOT (FALSE AND TRUE)

func (*Query) WherePK

func (q *Query) WherePK() *Query

WherePK adds condition based on the model primary keys. Usually it is the same as:

Where("id = ?id")

func (*Query) WhereStruct

func (q *Query) WhereStruct(strct interface{}) *Query

WhereStruct generates conditions for the struct fields with non-zero values:

- Foo int - Where("foo = ?", strct.Foo)
- Foo []int - Where("foo = ANY(?)", pg.Array(strct.Foo))
- FooNEQ int - Where("foo != ?", strct.Foo)
- FooExclude int - Where("foo != ?", strct.Foo)
- FooGT int - Where("foo > ?", strct.Foo)
- FooGTE int - Where("foo >= ?", strct.Foo)
- FooLT int - Where("foo < ?", strct.Foo)
- FooLTE int - Where("foo <= ?", strct.Foo)

urlstruct.Decode can be used to decode url.Values into the struct.

Following field tags are recognized:

- pg:"-" - field is ignored.
- pg:",nowhere" - field is decoded but is ignored by WhereStruct.
- pg:",nodecode" - field is not decoded but is used by WhereStruct.
- pg:",required" - condition is added for zero values as well.

func (*Query) With

func (q *Query) With(name string, subq *Query) *Query

With adds subq as common table expression with the given name.

func (*Query) WithDelete

func (q *Query) WithDelete(name string, subq *Query) *Query

func (*Query) WithInsert

func (q *Query) WithInsert(name string, subq *Query) *Query

func (*Query) WithUpdate

func (q *Query) WithUpdate(name string, subq *Query) *Query

func (*Query) WrapWith

func (q *Query) WrapWith(name string) *Query

WrapWith creates new Query and adds to it current query as common table expression with the given name.

type QueryAppender

type QueryAppender interface {
	AppendQuery(fmter QueryFormatter, b []byte) ([]byte, error)
}

type QueryFormatter

type QueryFormatter interface {
	FormatQuery(b []byte, query string, params ...interface{}) []byte
}

type Relation

type Relation struct {
	Type        int
	Field       *Field
	JoinTable   *Table
	FKs         []*Field
	Polymorphic *Field
	FKValues    []*Field

	M2MTableName  types.Safe
	M2MTableAlias types.Safe
	BaseFKs       []string
	JoinFKs       []string
}

func (*Relation) String

func (r *Relation) String() string

type Result

type Result interface {
	Model() Model

	// RowsAffected returns the number of rows affected by SELECT, INSERT, UPDATE,
	// or DELETE queries. It returns -1 if query can't possibly affect any rows,
	// e.g. in case of CREATE or SHOW queries.
	RowsAffected() int

	// RowsReturned returns the number of rows returned by the query.
	RowsReturned() int
}

Result summarizes an executed SQL command.

type SafeQueryAppender

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

func SafeQuery

func SafeQuery(query string, params ...interface{}) *SafeQueryAppender

nolint

func (*SafeQueryAppender) AppendQuery

func (q *SafeQueryAppender) AppendQuery(fmter QueryFormatter, b []byte) ([]byte, error)

func (*SafeQueryAppender) AppendValue

func (q *SafeQueryAppender) AppendValue(b []byte, quote int) ([]byte, error)

func (*SafeQueryAppender) Value

func (q *SafeQueryAppender) Value() types.Safe

type Table

type Table struct {
	Type reflect.Type

	TypeName  string
	Alias     types.Safe
	ModelName string

	Name               string
	FullName           types.Safe
	FullNameForSelects types.Safe

	Tablespace types.Safe

	PartitionBy string

	Fields     []*Field // PKs + DataFields
	PKs        []*Field
	DataFields []*Field

	FieldsMap map[string]*Field

	Methods   map[string]*Method
	Relations map[string]*Relation
	Unique    map[string][]*Field

	SoftDeleteField    *Field
	SetSoftDeleteField func(fv reflect.Value)
	// contains filtered or unexported fields
}

Table represents a SQL table created from Go struct.

func GetTable

func GetTable(typ reflect.Type) *Table

GetTable returns a Table for a struct type.

func (*Table) AddField

func (t *Table) AddField(field *Field)

func (*Table) AppendParam

func (t *Table) AppendParam(b []byte, strct reflect.Value, name string) ([]byte, bool)

func (*Table) GetField

func (t *Table) GetField(name string) (*Field, error)

func (*Table) HasField

func (t *Table) HasField(name string) bool

func (*Table) RemoveField

func (t *Table) RemoveField(field *Field)

func (*Table) String

func (t *Table) String() string

type TableModel

type TableModel interface {
	Model

	IsNil() bool
	Table() *Table
	Relation() *Relation
	AppendParam(QueryFormatter, []byte, string) ([]byte, bool)

	Join(string, func(*Query) (*Query, error)) *join
	GetJoin(string) *join
	GetJoins() []join
	AddJoin(join) *join

	Root() reflect.Value
	Index() []int
	ParentIndex() []int
	Mount(reflect.Value)
	Kind() reflect.Kind
	Value() reflect.Value
	// contains filtered or unexported methods
}

type TemplateAppender

type TemplateAppender interface {
	AppendTemplate(b []byte) ([]byte, error)
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL