schema

package
v1.2.16 Latest Latest
Warning

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

 Go to latest Published: Nov 20, 2025 License: BSD-2-Clause Imports: 28 Imported by: 97

Documentation

Index

Constants

View Source 
const (
	InvalidRelation = iota
	HasOneRelation
	BelongsToRelation
	HasManyRelation
	ManyToManyRelation
)

Variables

This section is empty.

Functions

func AppendBoolValue added in v0.1.6 

func AppendBoolValue(gen QueryGen, b []byte, v reflect.Value) []byte

func AppendFloat32Value added in v0.1.6 

func AppendFloat32Value(gen QueryGen, b []byte, v reflect.Value) []byte

func AppendFloat64Value added in v0.1.6 

func AppendFloat64Value(gen QueryGen, b []byte, v reflect.Value) []byte

func AppendIntValue 

func AppendIntValue(gen QueryGen, b []byte, v reflect.Value) []byte

func AppendJSONValue added in v0.3.4 

func AppendJSONValue(gen QueryGen, b []byte, v reflect.Value) []byte

func AppendOrder added in v1.2.16 

func AppendOrder(b []byte, sortDir Order) []byte

func AppendQueryAppender 

func AppendQueryAppender(gen QueryGen, b []byte, app QueryAppender) []byte

func AppendStringValue added in v0.3.4 

func AppendStringValue(gen QueryGen, b []byte, v reflect.Value) []byte

func AppendUintValue 

func AppendUintValue(gen QueryGen, b []byte, v reflect.Value) []byte

func DiscoverSQLType added in v0.1.17 

func DiscoverSQLType(typ reflect.Type) string

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.

Types

type AfterScanRowHook added in v1.0.13 

type AfterScanRowHook interface {
	AfterScanRow(context.Context) error
}

type AppenderFunc 

type AppenderFunc func(gen QueryGen, b []byte, v reflect.Value) []byte

func Appender 

func Appender(dialect Dialect, typ reflect.Type) AppenderFunc

func FieldAppender 

func FieldAppender(dialect Dialect, field *Field) AppenderFunc

func PtrAppender added in v1.0.3 

func PtrAppender(fn AppenderFunc) AppenderFunc

type BaseDialect added in v1.0.14 

type BaseDialect struct{}

func (BaseDialect) AppendBool added in v1.1.9 

func (BaseDialect) AppendBool(b []byte, v bool) []byte

func (BaseDialect) AppendBytes added in v1.0.14 

func (BaseDialect) AppendBytes(b, bs []byte) []byte

func (BaseDialect) AppendJSON added in v1.0.14 

func (BaseDialect) AppendJSON(b, jsonb []byte) []byte

func (BaseDialect) AppendString added in v1.0.17 

func (BaseDialect) AppendString(b []byte, s string) []byte

func (BaseDialect) AppendTime added in v1.0.14 

func (BaseDialect) AppendTime(b []byte, tm time.Time) []byte

func (BaseDialect) AppendUint32 added in v1.0.14 

func (BaseDialect) AppendUint32(b []byte, n uint32) []byte

func (BaseDialect) AppendUint64 added in v1.0.14 

func (BaseDialect) AppendUint64(b []byte, n uint64) []byte

type BaseModel added in v0.3.1 

type BaseModel struct{}

type BeforeAppendModelHook added in v1.0.13 

type BeforeAppendModelHook interface {
	BeforeAppendModel(ctx context.Context, query Query) error
}

type BeforeScanRowHook added in v1.0.13 

type BeforeScanRowHook interface {
	BeforeScanRow(context.Context) error
}

type ColumnsAppender 

type ColumnsAppender interface {
	AppendColumns(gen QueryGen, b []byte) ([]byte, error)
}

type CustomAppender added in v0.3.4 

type CustomAppender func(typ reflect.Type) AppenderFunc

type Dialect 

type Dialect interface {
	Init(db *sql.DB)

	Name() dialect.Name
	Features() feature.Feature

	Tables() *Tables
	OnTable(table *Table)

	IdentQuote() byte

	AppendUint32(b []byte, n uint32) []byte
	AppendUint64(b []byte, n uint64) []byte
	AppendTime(b []byte, tm time.Time) []byte
	AppendString(b []byte, s string) []byte
	AppendBytes(b []byte, bs []byte) []byte
	AppendJSON(b, jsonb []byte) []byte
	AppendBool(b []byte, v bool) []byte

	// AppendSequence adds the appropriate instruction for the driver to create a sequence
	// from which (autoincremented) values for the column will be generated.
	AppendSequence(b []byte, t *Table, f *Field) []byte

	// DefaultVarcharLen should be returned for dialects in which specifying VARCHAR length
	// is mandatory in queries that modify the schema (CREATE TABLE / ADD COLUMN, etc).
	// Dialects that do not have such requirement may return 0, which should be interpreted so by the caller.
	DefaultVarcharLen() int

	// DefaultSchema should returns the name of the default database schema.
	DefaultSchema() string
}

type Field 

type Field struct {
	Table       *Table // Contains this field
	StructField reflect.StructField
	IsPtr       bool

	Tag          tagparser.Tag
	IndirectType reflect.Type
	Index        []int

	Name    string // SQL name, .e.g. id
	SQLName Safe   // escaped SQL name, e.g. "id"
	GoName  string // struct field name, e.g. Id

	DiscoveredSQLType  string
	UserSQLType        string
	CreateTableSQLType string
	SQLDefault         string

	OnDelete string
	OnUpdate string

	IsPK          bool
	NotNull       bool
	NullZero      bool
	AutoIncrement bool
	Identity      bool

	Append AppenderFunc
	Scan   ScannerFunc
	IsZero IsZeroerFunc
}

func (*Field) AppendValue 

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

func (*Field) Clone 

func (f *Field) Clone() *Field

func (*Field) HasNilValue added in v1.1.1 

func (f *Field) HasNilValue(v reflect.Value) bool

func (*Field) HasZeroValue 

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

func (*Field) ScanValue 

func (f *Field) ScanValue(strct reflect.Value, src any) error

func (*Field) ScanWithCheck 

func (f *Field) ScanWithCheck(fv reflect.Value, src any) error

func (*Field) SkipUpdate added in v1.1.6 

func (f *Field) SkipUpdate() bool

func (*Field) String 

func (f *Field) String() string

func (*Field) Value 

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

func (*Field) WithIndex added in v1.2.0 

func (f *Field) WithIndex(path []int) *Field

type Ident 

type Ident string

Ident represents a SQL identifier, for example, a fully qualified column name such as `table_name.col_name`.

func (Ident) AppendQuery 

func (s Ident) AppendQuery(gen QueryGen, b []byte) ([]byte, error)

type IsZeroerFunc 

type IsZeroerFunc func(reflect.Value) bool

type Model added in v1.0.13 

type Model interface {
	ScanRows(ctx context.Context, rows *sql.Rows) (int, error)
	Value() any
}

type Name added in v1.1.15 

type Name string

Name represents a single SQL name, for example, a column name.

func (Name) AppendQuery added in v1.1.15 

func (s Name) AppendQuery(gen QueryGen, b []byte) ([]byte, error)

type NamedArgAppender added in v0.4.0 

type NamedArgAppender interface {
	AppendNamedArg(gen QueryGen, b []byte, name string) ([]byte, bool)
}

type NullTime added in v0.1.17 

type NullTime struct {
	time.Time
}

NullTime is a time.Time wrapper that marshals zero time as JSON null and SQL NULL.

func (NullTime) AppendQuery added in v0.1.17 

func (tm NullTime) AppendQuery(gen QueryGen, b []byte) ([]byte, error)

func (NullTime) MarshalJSON added in v0.1.17 

func (tm NullTime) MarshalJSON() ([]byte, error)

func (*NullTime) Scan added in v0.1.17 

func (tm *NullTime) Scan(src any) error

func (*NullTime) UnmarshalJSON added in v0.1.17 

func (tm *NullTime) UnmarshalJSON(b []byte) error

type Order added in v1.2.16 

type Order string
const (
	OrderNone           Order = ""
	OrderAsc            Order = "ASC"
	OrderAscNullsFirst  Order = "ASC NULLS FIRST"
	OrderAscNullsLast   Order = "ASC NULLS LAST"
	OrderDesc           Order = "DESC"
	OrderDescNullsFirst Order = "DESC NULLS FIRST"
	OrderDescNullsLast  Order = "DESC NULLS LAST"
)

func (Order) AppendQuery added in v1.2.16 

func (s Order) AppendQuery(gen QueryGen, b []byte) ([]byte, error)

type Query added in v1.0.5 

type Query interface {
	QueryAppender
	Operation() string
	GetModel() Model
	GetTableName() string
}

type QueryAppender 

type QueryAppender interface {
	AppendQuery(gen QueryGen, b []byte) ([]byte, error)
}

func In added in v1.1.2 

func In(slice any) QueryAppender

func NullZero added in v1.1.15 

func NullZero(value any) QueryAppender

type QueryGen added in v1.2.16 

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

func NewNopQueryGen added in v1.2.16 

func NewNopQueryGen() QueryGen

func NewQueryGen added in v1.2.16 

func NewQueryGen(dialect Dialect) QueryGen

func (QueryGen) Append added in v1.2.16 

func (gen QueryGen) Append(b []byte, v any) []byte

func (QueryGen) AppendIdent added in v1.2.16 

func (f QueryGen) AppendIdent(b []byte, ident string) []byte

func (QueryGen) AppendName added in v1.2.16 

func (f QueryGen) AppendName(b []byte, name string) []byte

func (QueryGen) AppendQuery added in v1.2.16 

func (f QueryGen) AppendQuery(dst []byte, query string, args ...any) []byte

func (QueryGen) AppendValue added in v1.2.16 

func (f QueryGen) AppendValue(b []byte, v reflect.Value) []byte

func (QueryGen) Dialect added in v1.2.16 

func (f QueryGen) Dialect() Dialect

func (QueryGen) FormatQuery added in v1.2.16 

func (f QueryGen) FormatQuery(query string, args ...any) string

func (QueryGen) HasFeature added in v1.2.16 

func (f QueryGen) HasFeature(feature feature.Feature) bool

func (QueryGen) IdentQuote added in v1.2.16 

func (f QueryGen) IdentQuote() byte

func (QueryGen) IsNop added in v1.2.16 

func (f QueryGen) IsNop() bool

func (QueryGen) WithArg added in v1.2.16 

func (f QueryGen) WithArg(arg NamedArgAppender) QueryGen

func (QueryGen) WithNamedArg added in v1.2.16 

func (f QueryGen) WithNamedArg(name string, value any) QueryGen

type QueryWithArgs 

type QueryWithArgs struct {
	Query string
	Args  []any
}

NOTE: It should not be modified after creation.

func SafeQuery 

func SafeQuery(query string, args []any) QueryWithArgs

func UnsafeIdent 

func UnsafeIdent(ident string) QueryWithArgs

func (QueryWithArgs) AppendQuery 

func (q QueryWithArgs) AppendQuery(gen QueryGen, b []byte) ([]byte, error)

func (QueryWithArgs) IsZero 

func (q QueryWithArgs) IsZero() bool

type QueryWithSep 

type QueryWithSep struct {
	QueryWithArgs
	Sep string
}

func SafeQueryWithSep 

func SafeQueryWithSep(query string, args []any, sep string) QueryWithSep

type Relation 

type Relation struct {
	Type  int
	Field *Field // Has the bun tag defining this relation.

	// Base and Join can be explained with this query:
	//
	// SELECT * FROM base_table JOIN join_table
	JoinTable *Table
	BasePKs   []*Field
	JoinPKs   []*Field
	OnUpdate  string
	OnDelete  string
	Condition []string

	PolymorphicField *Field
	PolymorphicValue string

	M2MTable   *Table
	M2MBasePKs []*Field
	M2MJoinPKs []*Field
}

func (*Relation) References added in v1.1.17 

func (r *Relation) References() bool

References returns true if the table which defines this Relation needs to declare a foreign key constraint, as is the case for 'has-one' and 'belongs-to' relations. For other relations, the constraint is created either in the referencing table (1:N, 'has-many' relations) or the junction table (N:N, 'm2m' relations).

Usage of `rel:` tag does not always imply creation of foreign keys (when WithForeignKeys() is not set) and can be used exclusively for joining tables at query time. For example: 

type User struct {
	ID int64			`bun:",pk"`
	Profile *Profile	`bun:",rel:has-one,join:id=user_id"`
}

Creating a FK users.id -> profiles.user_id would be confusing and incorrect, so for such cases References() returns false. One notable exception to this rule is when a Relation is defined in a junction table, in which case it is perfectly fine for its primary keys to reference other tables. Consider: 

// UsersToGroups maps users to groups they follow.
type UsersToGroups struct {
	UserID string	`bun:"user_id,pk"`		// Needs FK to users.id
	GroupID string	`bun:"group_id,pk"`		// Needs FK to groups.id

	User	*User	`bun:"rel:belongs-to,join:user_id=id"`
	Group	*Group	`bun:"rel:belongs-to,join:group_id=id"`
}

Here BooksToReaders has a composite primary key, composed of other primary keys.

func (*Relation) String 

func (r *Relation) String() string

type Safe 

type Safe string

Safe represents a safe SQL query.

func (Safe) AppendQuery 

func (s Safe) AppendQuery(gen QueryGen, b []byte) ([]byte, error)

type ScannerFunc 

type ScannerFunc func(dest reflect.Value, src any) error

func FieldScanner 

func FieldScanner(dialect Dialect, field *Field) ScannerFunc

func PtrScanner added in v1.0.3 

func PtrScanner(fn ScannerFunc) ScannerFunc

func Scanner 

func Scanner(typ reflect.Type) ScannerFunc

type Table 

type Table struct {
	Type      reflect.Type
	ZeroValue reflect.Value // reflect.Struct
	ZeroIface any           // struct pointer

	TypeName  string
	ModelName string

	Schema            string
	Name              string
	SQLName           Safe
	SQLNameForSelects Safe
	Alias             string
	SQLAlias          Safe

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

	FieldMap  map[string]*Field
	StructMap map[string]*structField

	IsM2MTable bool // If true, this table is the "junction table" of an m2m relation.
	Relations  map[string]*Relation
	Unique     map[string][]*Field

	SoftDeleteField       *Field
	UpdateSoftDeleteField func(fv reflect.Value, tm time.Time) error
	// contains filtered or unexported fields
}

Table represents a SQL table created from Go struct.

func (*Table) AppendNamedArg added in v0.4.3 

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

func (*Table) CheckPKs 

func (t *Table) CheckPKs() error

func (*Table) Dialect 

func (t *Table) Dialect() Dialect

func (*Table) Field 

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

func (*Table) HasAfterScanRowHook added in v1.0.13 

func (t *Table) HasAfterScanRowHook() bool

func (*Table) HasBeforeAppendModelHook added in v1.0.13 

func (t *Table) HasBeforeAppendModelHook() bool

func (*Table) HasBeforeScanRowHook added in v1.0.13 

func (t *Table) HasBeforeScanRowHook() bool

func (*Table) HasField 

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

func (*Table) LookupField added in v1.2.0 

func (t *Table) LookupField(name string) *Field

func (*Table) String 

func (t *Table) String() string

type Tables 

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

func NewTables 

func NewTables(dialect Dialect) *Tables

func (*Tables) All added in v1.2.6 

func (t *Tables) All() []*Table

All returns all registered tables.

func (*Tables) ByModel 

func (t *Tables) ByModel(name string) *Table

ByModel gets the table by its Go name.

func (*Tables) ByName 

func (t *Tables) ByName(name string) *Table

ByName gets the table by its SQL name.

func (*Tables) Get 

func (t *Tables) Get(typ reflect.Type) *Table

func (*Tables) InProgress added in v1.2.0 

func (t *Tables) InProgress(typ reflect.Type) *Table

func (*Tables) Register 

func (t *Tables) Register(models ...any)

Source Files

View all Source files

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.