db

package
v1.22.5 Latest Latest
Warning

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

 Go to latest Published: Dec 11, 2024 License: MIT Imports: 28 Imported by: 96

Documentation

Index

Constants

View Source 
const (
	// DefaultMaxInSize represents default variables number on IN () in SQL
	DefaultMaxInSize = 50
)
View Source 
const (
	// Which means a condition to filter the records which don't match any id.
	// It's different from zero which means the condition could be ignored.
	NoConditionID = -1
)

Variables

View Source 
var (
	// ErrResouceOutdated represents an error when request resource outdated
	ErrResouceOutdated = errors.New("resource outdated")
	// ErrGetResourceIndexFailed represents an error when resource index retries 3 times
	ErrGetResourceIndexFailed = errors.New("get resource index failed")
)
View Source 
var (
	// ErrNameEmpty name is empty error
	ErrNameEmpty = util.SilentWrap{Message: "name is empty", Err: util.ErrInvalidArgument}

	// AlphaDashDotPattern characters prohibited in a user name (anything except A-Za-z0-9_.-)
	AlphaDashDotPattern = regexp.MustCompile(`[^\w-\.]`)
)
View Source 
var DefaultContext context.Context

DefaultContext is the default context to run xorm queries in will be overwritten by Init with HammerContext

View Source 
var ListOptionsAll = ListOptions{ListAll: true}

Functions

func BuildCaseInsensitiveIn added in v1.21.0 

func BuildCaseInsensitiveIn(key string, values []string) builder.Cond

BuildCaseInsensitiveIn returns a condition to check if the given value is in the given values case-insensitively. Handles especially SQLite correctly as UPPER there only transforms ASCII letters.

func BuildCaseInsensitiveLike added in v1.17.4 

func BuildCaseInsensitiveLike(key, value string) builder.Cond

BuildCaseInsensitiveLike returns a condition to check if the given value is like the given key case-insensitively. Handles especially SQLite correctly as UPPER there only transforms ASCII letters.

func BuilderDialect added in v1.20.3 

func BuilderDialect() string

BuilderDialect returns the xorm.Builder dialect of the engine

func Cell2Int64 

func Cell2Int64(val xorm.Cell) int64

Cell2Int64 converts a xorm.Cell type to int64, and handles possible irregular cases.

func ConvertDatabaseTable added in v1.22.0 

func ConvertDatabaseTable() error

ConvertDatabaseTable converts database and tables from utf8 to utf8mb4 if it's mysql and set ROW_FORMAT=dynamic

func ConvertVarcharToNVarchar added in v1.19.2 

func ConvertVarcharToNVarchar() error

ConvertVarcharToNVarchar converts database and tables from varchar to nvarchar if it's mssql

func Count 

func Count[T any](ctx context.Context, opts FindOptions) (int64, error)

Count represents a common count function which accept an options interface

func CountBadSequences 

func CountBadSequences(_ context.Context) (int64, error)

CountBadSequences looks for broken sequences from recreate-table mistakes

func CountByBean 

func CountByBean(ctx context.Context, bean any) (int64, error)

CountByBean counts the number of database records according non-empty fields of the bean as conditions.

func CountOrphanedObjects added in v1.17.0 

func CountOrphanedObjects(ctx context.Context, subject, refObject, joinCond string) (int64, error)

CountOrphanedObjects count subjects with have no existing refobject anymore

func DecrByIDs added in v1.19.0 

func DecrByIDs(ctx context.Context, ids []int64, decrCol string, bean any) error

DecrByIDs decreases the given column for entities of the "bean" type with one of the given ids by one Timestamps of the entities won't be updated

func Delete added in v1.22.0 

func Delete[T any](ctx context.Context, opts FindOptions) (int64, error)

func DeleteAllRecords 

func DeleteAllRecords(tableName string) error

DeleteAllRecords will delete all the records of this table

func DeleteBeans added in v1.17.0 

func DeleteBeans(ctx context.Context, beans ...any) (err error)

DeleteBeans deletes all given beans, beans must contain delete conditions.

func DeleteByBean 

func DeleteByBean(ctx context.Context, bean any) (int64, error)

DeleteByBean deletes all records according non-empty fields of the bean as conditions.

func DeleteByID added in v1.19.0 

func DeleteByID[T any](ctx context.Context, id int64) (int64, error)

DeleteByID deletes the given bean with the given ID

func DeleteByIDs added in v1.22.0 

func DeleteByIDs[T any](ctx context.Context, ids ...int64) error

func DeleteOrphanedObjects added in v1.17.0 

func DeleteOrphanedObjects(ctx context.Context, subject, refObject, joinCond string) error

DeleteOrphanedObjects delete subjects with have no existing refobject anymore

func DeleteResourceIndex added in v1.17.4 

func DeleteResourceIndex(ctx context.Context, tableName string, groupID int64) error

DeleteResourceIndex delete resource index

func DumpDatabase 

func DumpDatabase(filePath, dbType string) error

DumpDatabase dumps all data from database according the special database SQL syntax to file system.

func DumpTables 

func DumpTables(tables []*schemas.Table, w io.Writer, tp ...schemas.DBType) error

DumpTables dump tables information

func ErrCancelledf 

func ErrCancelledf(format string, args ...any) error

ErrCancelledf returns an ErrCancelled for the provided format and args

func Exec 

func Exec(ctx context.Context, sqlAndArgs ...any) (sql.Result, error)

Exec executes a sql with args

func Exist added in v1.21.2 

func Exist[T any](ctx context.Context, cond builder.Cond) (bool, error)

func ExistByID added in v1.22.0 

func ExistByID[T any](ctx context.Context, id int64) (bool, error)

func Find added in v1.18.4 

func Find[T any](ctx context.Context, opts FindOptions) ([]*T, error)

Find represents a common find function which accept an options interface

func FindAndCount added in v1.18.4 

func FindAndCount[T any](ctx context.Context, opts FindOptions) ([]*T, int64, error)

FindAndCount represents a common findandcount function which accept an options interface

func FindIDs added in v1.19.0 

func FindIDs(ctx context.Context, tableName, idCol string, cond builder.Cond) ([]int64, error)

FindIDs finds the IDs for the given table name satisfying the given condition By passing a different value than "id" for "idCol", you can query for foreign IDs, i.e. the repo IDs which satisfy the condition

func FixBadSequences 

func FixBadSequences(_ context.Context) error

FixBadSequences fixes for broken sequences from recreate-table mistakes

func Get added in v1.22.0 

func Get[T any](ctx context.Context, cond builder.Cond) (object *T, exist bool, err error)

func GetByID added in v1.22.0 

func GetByID[T any](ctx context.Context, id int64) (object *T, exist bool, err error)

func GetMaxID 

func GetMaxID(beanOrTableName any) (maxID int64, err error)

GetMaxID will return max id of the table

func GetNextResourceIndex 

func GetNextResourceIndex(ctx context.Context, tableName string, groupID int64) (int64, error)

GetNextResourceIndex generates a resource index, it must run in the same transaction where the resource is created

func InTransaction added in v1.17.4 

func InTransaction(ctx context.Context) bool

InTransaction returns true if the engine is in a transaction otherwise return false

func InitEngine 

func InitEngine(ctx context.Context) error

InitEngine initializes the xorm.Engine and sets it as db.DefaultContext

func InitEngineWithMigration 

func InitEngineWithMigration(ctx context.Context, migrateFunc func(*xorm.Engine) error) (err error)

InitEngineWithMigration initializes a new xorm.Engine and sets it as the db.DefaultContext This function must never call .Sync() if the provided migration function fails. When called from the "doctor" command, the migration function is a version check that prevents the doctor from fixing anything in the database if the migration level is different from the expected value.

func Insert 

func Insert(ctx context.Context, beans ...any) error

Insert inserts records into database

func IsErrCancelled 

func IsErrCancelled(err error) bool

IsErrCancelled checks if an error is a ErrCancelled.

func IsErrNameCharsNotAllowed 

func IsErrNameCharsNotAllowed(err error) bool

IsErrNameCharsNotAllowed checks if an error is an ErrNameCharsNotAllowed.

func IsErrNamePatternNotAllowed 

func IsErrNamePatternNotAllowed(err error) bool

IsErrNamePatternNotAllowed checks if an error is an ErrNamePatternNotAllowed.

func IsErrNameReserved 

func IsErrNameReserved(err error) bool

IsErrNameReserved checks if an error is a ErrNameReserved.

func IsErrNotExist added in v1.17.0 

func IsErrNotExist(err error) bool

IsErrNotExist checks if an error is an ErrNotExist

func IsErrSSHDisabled 

func IsErrSSHDisabled(err error) bool

IsErrSSHDisabled checks if an error is a ErrSSHDisabled.

func IsTableNotEmpty 

func IsTableNotEmpty(beanOrTableName any) (bool, error)

IsTableNotEmpty returns true if table has at least one record

func IsUsableName 

func IsUsableName(names, patterns []string, name string) error

IsUsableName checks if name is reserved or pattern of name is not allowed based on given reserved names and patterns. Names are exact match, patterns can be prefix or suffix match with placeholder '*'.

func Iterate 

func Iterate[Bean any](ctx context.Context, cond builder.Cond, f func(ctx context.Context, bean *Bean) error) error

Iterate iterate all the Bean object

func MaxBatchInsertSize 

func MaxBatchInsertSize(bean any) int

MaxBatchInsertSize returns the table's max batch insert size

func NamesToBean 

func NamesToBean(names ...string) ([]any, error)

NamesToBean return a list of beans or an error

func NewXORMLogger 

func NewXORMLogger(showSQL bool) xormlog.Logger

NewXORMLogger inits a log bridge for xorm

func RegisterModel 

func RegisterModel(bean any, initFunc ...func() error)

RegisterModel registers model, if initfunc provided, it will be invoked after data model sync

func SetDefaultEngine 

func SetDefaultEngine(ctx context.Context, eng *xorm.Engine)

SetDefaultEngine sets the default engine for db

func SetLogSQL added in v1.17.4 

func SetLogSQL(ctx context.Context, on bool)

func SetSessionPagination 

func SetSessionPagination(sess Engine, p Paginator) *xorm.Session

SetSessionPagination sets pagination for a database session

func SyncAllTables 

func SyncAllTables() error

SyncAllTables sync the schemas of all tables, is required by unit test code

func SyncMaxResourceIndex added in v1.17.4 

func SyncMaxResourceIndex(ctx context.Context, tableName string, groupID, maxIndex int64) (err error)

SyncMaxResourceIndex sync the max index with the resource

func TableInfo 

func TableInfo(v any) (*schemas.Table, error)

TableInfo returns table's information via an object

func TableName 

func TableName(bean any) string

TableName returns the table name according a bean object

func TruncateBeans added in v1.20.0 

func TruncateBeans(ctx context.Context, beans ...any) (err error)

TruncateBeans deletes all given beans, beans may contain delete conditions.

func TxContext 

func TxContext(parentCtx context.Context) (*Context, Committer, error)

TxContext represents a transaction Context, it will reuse the existing transaction in the parent context or create a new one. Some tips to use: 

1 It's always recommended to use `WithTx` in new code instead of `TxContext`, since `WithTx` will handle the transaction automatically.
2. To maintain the old code which uses `TxContext`:
  a. Always call `Close()` before returning regardless of whether `Commit()` has been called.
  b. Always call `Commit()` before returning if there are no errors, even if the code did not change any data.
  c. Remember the `Committer` will be a halfCommitter when a transaction is being reused.
     So calling `Commit()` will do nothing, but calling `Close()` without calling `Commit()` will rollback the transaction.
     And all operations submitted by the caller stack will be rollbacked as well, not only the operations in the current function.
  d. It doesn't mean rollback is forbidden, but always do it only when there is an error, and you do want to rollback.

func UnsetDefaultEngine 

func UnsetDefaultEngine()

UnsetDefaultEngine closes and unsets the default engine We hope the SetDefaultEngine and UnsetDefaultEngine can be paired, but it's impossible now, there are many calls to InitEngine -> SetDefaultEngine directly to overwrite the `x` and DefaultContext without close Global database engine related functions are all racy and there is no graceful close right now.

func WithTx 

func WithTx(parentCtx context.Context, f func(ctx context.Context) error) error

WithTx represents executing database operations on a transaction, if the transaction exist, this function will reuse it otherwise will create a new one and close it when finished.

Types

type AbsoluteListOptions 

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

AbsoluteListOptions absolute options to paginate results

func NewAbsoluteListOptions 

func NewAbsoluteListOptions(skip, take int) *AbsoluteListOptions

NewAbsoluteListOptions creates a list option with applied limits

func (*AbsoluteListOptions) GetSkipTake 

func (opts *AbsoluteListOptions) GetSkipTake() (skip, take int)

GetSkipTake returns the skip and take values

func (*AbsoluteListOptions) IsListAll added in v1.18.4 

func (opts *AbsoluteListOptions) IsListAll() bool

IsListAll will always return false

type CheckCollationsResult added in v1.22.0 

type CheckCollationsResult struct {
	ExpectedCollation        string
	AvailableCollation       container.Set[string]
	DatabaseCollation        string
	IsCollationCaseSensitive func(s string) bool
	CollationEquals          func(a, b string) bool
	ExistingTableNumber      int

	InconsistentCollationColumns []string
}

func CheckCollations added in v1.22.0 

func CheckCollations(x *xorm.Engine) (*CheckCollationsResult, error)

func CheckCollationsDefaultEngine added in v1.22.0 

func CheckCollationsDefaultEngine() (*CheckCollationsResult, error)

type Committer 

type Committer interface {
	Commit() error
	Close() error
}

Committer represents an interface to Commit or Close the Context

type Context 

type Context struct {
	context.Context
	// contains filtered or unexported fields
}

Context represents a db context

func (*Context) Engine 

func (ctx *Context) Engine() Engine

Engine returns db engine

func (*Context) InTransaction added in v1.17.4 

func (ctx *Context) InTransaction() bool

InTransaction if context is in a transaction

func (*Context) Value 

func (ctx *Context) Value(key any) any

Value shadows Value for context.Context but allows us to get ourselves and an Engined object

func (*Context) WithContext added in v1.17.0 

func (ctx *Context) WithContext(other context.Context) *Context

WithContext returns this engine tied to this context

type Engine 

type Engine interface {
	Table(tableNameOrBean any) *xorm.Session
	Count(...any) (int64, error)
	Decr(column string, arg ...any) *xorm.Session
	Delete(...any) (int64, error)
	Truncate(...any) (int64, error)
	Exec(...any) (sql.Result, error)
	Find(any, ...any) error
	Get(beans ...any) (bool, error)
	ID(any) *xorm.Session
	In(string, ...any) *xorm.Session
	Incr(column string, arg ...any) *xorm.Session
	Insert(...any) (int64, error)
	Iterate(any, xorm.IterFunc) error
	Join(joinOperator string, tablename, condition any, args ...any) *xorm.Session
	SQL(any, ...any) *xorm.Session
	Where(any, ...any) *xorm.Session
	Asc(colNames ...string) *xorm.Session
	Desc(colNames ...string) *xorm.Session
	Limit(limit int, start ...int) *xorm.Session
	NoAutoTime() *xorm.Session
	SumInt(bean any, columnName string) (res int64, err error)
	Sync(...any) error
	Select(string) *xorm.Session
	SetExpr(string, any) *xorm.Session
	NotIn(string, ...any) *xorm.Session
	OrderBy(any, ...any) *xorm.Session
	Exist(...any) (bool, error)
	Distinct(...string) *xorm.Session
	Query(...any) ([]map[string][]byte, error)
	Cols(...string) *xorm.Session
	Context(ctx context.Context) *xorm.Session
	Ping() error
}

Engine represents a xorm engine or session.

func GetEngine 

func GetEngine(ctx context.Context) Engine

GetEngine will get a db Engine from this context or return an Engine restricted to this context

type Engined 

type Engined interface {
	Engine() Engine
}

Engined structs provide an Engine

type ErrCancelled 

type ErrCancelled struct {
	Message string
}

ErrCancelled represents an error due to context cancellation

func (ErrCancelled) Error 

func (err ErrCancelled) Error() string

type ErrNameCharsNotAllowed 

type ErrNameCharsNotAllowed struct {
	Name string
}

ErrNameCharsNotAllowed represents a "character not allowed in name" error.

func (ErrNameCharsNotAllowed) Error 

func (err ErrNameCharsNotAllowed) Error() string

func (ErrNameCharsNotAllowed) Unwrap added in v1.17.4 

func (err ErrNameCharsNotAllowed) Unwrap() error

Unwrap unwraps this as a ErrInvalid err

type ErrNamePatternNotAllowed 

type ErrNamePatternNotAllowed struct {
	Pattern string
}

ErrNamePatternNotAllowed represents a "pattern not allowed" error.

func (ErrNamePatternNotAllowed) Error 

func (err ErrNamePatternNotAllowed) Error() string

func (ErrNamePatternNotAllowed) Unwrap added in v1.17.4 

func (err ErrNamePatternNotAllowed) Unwrap() error

Unwrap unwraps this as a ErrInvalid err

type ErrNameReserved 

type ErrNameReserved struct {
	Name string
}

ErrNameReserved represents a "reserved name" error.

func (ErrNameReserved) Error 

func (err ErrNameReserved) Error() string

func (ErrNameReserved) Unwrap added in v1.17.4 

func (err ErrNameReserved) Unwrap() error

Unwrap unwraps this as a ErrInvalid err

type ErrNotExist added in v1.17.0 

type ErrNotExist struct {
	Resource string
	ID       int64
}

ErrNotExist represents a non-exist error.

func (ErrNotExist) Error added in v1.17.0 

func (err ErrNotExist) Error() string

func (ErrNotExist) Unwrap added in v1.17.4 

func (err ErrNotExist) Unwrap() error

Unwrap unwraps this as a ErrNotExist err

type ErrSSHDisabled 

type ErrSSHDisabled struct{}

ErrSSHDisabled represents an "SSH disabled" error.

func (ErrSSHDisabled) Error 

func (err ErrSSHDisabled) Error() string

type FindOptions added in v1.18.4 

type FindOptions interface {
	GetPage() int
	GetPageSize() int
	IsListAll() bool
	ToConds() builder.Cond
}

FindOptions represents a find options

type FindOptionsJoin added in v1.22.0 

type FindOptionsJoin interface {
	ToJoins() []JoinFunc
}

type FindOptionsOrder added in v1.22.0 

type FindOptionsOrder interface {
	ToOrders() string
}

type JoinFunc added in v1.22.0 

type JoinFunc func(sess Engine) error

type ListOptions 

type ListOptions struct {
	PageSize int
	Page     int  // start from 1
	ListAll  bool // if true, then PageSize and Page will not be taken
}

ListOptions options to paginate results

func (ListOptions) GetPage added in v1.22.0 

func (opts ListOptions) GetPage() int

func (ListOptions) GetPageSize added in v1.22.0 

func (opts ListOptions) GetPageSize() int

func (*ListOptions) GetSkipTake 

func (opts *ListOptions) GetSkipTake() (skip, take int)

GetSkipTake returns the skip and take values

func (ListOptions) IsListAll added in v1.18.4 

func (opts ListOptions) IsListAll() bool

IsListAll indicates PageSize and Page will be ignored

func (*ListOptions) SetDefaultValues 

func (opts *ListOptions) SetDefaultValues()

SetDefaultValues sets default values

func (ListOptions) ToConds added in v1.22.0 

func (opts ListOptions) ToConds() builder.Cond

type Paginator 

type Paginator interface {
	GetSkipTake() (skip, take int)
	IsListAll() bool
}

Paginator is the base for different ListOptions types

type ResourceIndex 

type ResourceIndex struct {
	GroupID  int64 `xorm:"pk"`
	MaxIndex int64 `xorm:"index"`
}

ResourceIndex represents a resource index which could be used as issue/release and others We can create different tables i.e. issue_index, release_index, etc.

type SearchOrderBy 

type SearchOrderBy string

SearchOrderBy is used to sort the result 

const (
	SearchOrderByAlphabetically        SearchOrderBy = "name ASC"
	SearchOrderByAlphabeticallyReverse SearchOrderBy = "name DESC"
	SearchOrderByLeastUpdated          SearchOrderBy = "updated_unix ASC"
	SearchOrderByRecentUpdated         SearchOrderBy = "updated_unix DESC"
	SearchOrderByOldest                SearchOrderBy = "created_unix ASC"
	SearchOrderByNewest                SearchOrderBy = "created_unix DESC"
	SearchOrderBySize                  SearchOrderBy = "size ASC"
	SearchOrderBySizeReverse           SearchOrderBy = "size DESC"
	SearchOrderByGitSize               SearchOrderBy = "git_size ASC"
	SearchOrderByGitSizeReverse        SearchOrderBy = "git_size DESC"
	SearchOrderByLFSSize               SearchOrderBy = "lfs_size ASC"
	SearchOrderByLFSSizeReverse        SearchOrderBy = "lfs_size DESC"
	SearchOrderByID                    SearchOrderBy = "id ASC"
	SearchOrderByIDReverse             SearchOrderBy = "id DESC"
	SearchOrderByStars                 SearchOrderBy = "num_stars ASC"
	SearchOrderByStarsReverse          SearchOrderBy = "num_stars DESC"
	SearchOrderByForks                 SearchOrderBy = "num_forks ASC"
	SearchOrderByForksReverse          SearchOrderBy = "num_forks DESC"
)

Strings for sorting result

func (SearchOrderBy) String 

func (s SearchOrderBy) String() string

type SlowQueryHook added in v1.22.0 

type SlowQueryHook struct {
	Threshold time.Duration
	Logger    log.Logger
}

func (*SlowQueryHook) AfterProcess added in v1.22.0 

func (h *SlowQueryHook) AfterProcess(c *contexts.ContextHook) error

func (SlowQueryHook) BeforeProcess added in v1.22.0 

func (SlowQueryHook) BeforeProcess(c *contexts.ContextHook) (context.Context, error)

type XORMLogBridge 

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

XORMLogBridge a logger bridge from Logger to xorm

func (*XORMLogBridge) Debug 

func (l *XORMLogBridge) Debug(v ...any)

Debug show debug log

func (*XORMLogBridge) Debugf 

func (l *XORMLogBridge) Debugf(format string, v ...any)

Debugf show debug log

func (*XORMLogBridge) Error 

func (l *XORMLogBridge) Error(v ...any)

Error show error log

func (*XORMLogBridge) Errorf 

func (l *XORMLogBridge) Errorf(format string, v ...any)

Errorf show error log

func (*XORMLogBridge) Info 

func (l *XORMLogBridge) Info(v ...any)

Info show information level log

func (*XORMLogBridge) Infof 

func (l *XORMLogBridge) Infof(format string, v ...any)

Infof show information level log

func (*XORMLogBridge) IsShowSQL 

func (l *XORMLogBridge) IsShowSQL() bool

IsShowSQL if record SQL

func (*XORMLogBridge) Level 

func (l *XORMLogBridge) Level() xormlog.LogLevel

Level get logger level

func (*XORMLogBridge) Log 

func (l *XORMLogBridge) Log(skip int, level log.Level, format string, v ...any)

Log a message with defined skip and at logging level

func (*XORMLogBridge) SetLevel 

func (l *XORMLogBridge) SetLevel(lvl xormlog.LogLevel)

SetLevel set the logger level

func (*XORMLogBridge) ShowSQL 

func (l *XORMLogBridge) ShowSQL(show ...bool)

ShowSQL set if record SQL

func (*XORMLogBridge) Warn 

func (l *XORMLogBridge) Warn(v ...any)

Warn show warning log

func (*XORMLogBridge) Warnf 

func (l *XORMLogBridge) Warnf(format string, v ...any)

Warnf show warnning log

Source Files

View all Source files

Directories

Path Synopsis

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.