db

package
v1.28.0-dev Latest Latest
Warning

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

 Go to latest Published: Jun 29, 2026 License: MIT Imports: 37 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// DefaultMaxInSize represents default variables number on IN () in SQL
	DefaultMaxInSize = 50
)
View Source 
const NoConditionID int64 = -1

NoConditionID means a condition to filter the records which don't match any id. eg: "milestone_id=-1" means "find the items without any milestone.

Variables

View Source 
var (
	ContextKeyTestFixtures = contextKey{"test-fixtures"}
)
View Source 
var ErrGetResourceIndexFailed = errors.New("get resource index failed")
View Source 
var ListOptionsAll = ListOptions{ListAll: true}

Functions

func BuildCaseInsensitiveIn 

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. See BuildCaseInsensitiveLike for more details

func BuildCaseInsensitiveLike 

func BuildCaseInsensitiveLike(key, value string) builder.Cond

BuildCaseInsensitiveLike returns a case-insensitive LIKE condition for the given key and value. Cast the search value and the database column value to the same case for case-insensitive matching. * SQLite: only cast ASCII chars because it doesn't handle complete Unicode case folding * Other databases: use database's string function, assuming that they are able to handle complete Unicode case folding correctly

func BuilderDialect 

func BuilderDialect() string

BuilderDialect returns the xorm.Builder dialect of the engine

func CellToInt 

func CellToInt[T ~int | int64](cell xorm.Cell, def T) (ret T, has bool, err error)

CellToInt converts a xorm.Cell field value to an int value

func ConnStr 

func ConnStr(opts ConnOptions) (string, string, error)

func ConnStrDefaultDatabase 

func ConnStrDefaultDatabase(opts ConnOptions) (string, string, error)

func ConvertDatabaseTable 

func ConvertDatabaseTable() error

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

func ConvertVarcharToNVarchar 

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 

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

CountOrphanedObjects count subjects with have no existing refobject anymore

func DecrByIDs 

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 

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 

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 

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

DeleteByID deletes the given bean with the given ID

func DeleteByIDs 

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

func DeleteOrphanedObjects 

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

DeleteOrphanedObjects delete subjects with have no existing refobject anymore

func DeleteResourceIndex 

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

DeleteResourceIndex delete resource index

func DumpDatabase 

func DumpDatabase(filePath string, dbType setting.DatabaseType) error

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

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 

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

func ExistByID 

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

func Find 

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

Find represents a common find function which accept an options interface

func FindAndCount 

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 

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 

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

func GetByID 

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 GetXORMEngineForTesting 

func GetXORMEngineForTesting() *xorm.Engine

func InTransaction 

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 XORM's default context

func InitEngineWithMigration 

func InitEngineWithMigration(ctx context.Context, migrateFunc func(context.Context, EngineMigration) error) (err error)

InitEngineWithMigration initializes a new xorm.Engine and sets it as the XORM's default context 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 

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(reservedNames, reservedPatterns []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 a 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 iterates 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 initFuncs 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 

func SetLogSQL(ctx context.Context, on bool)

func SetSessionPagination 

func SetSessionPagination(sess Engine, p Paginator)

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 

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

SyncMaxResourceIndex sync the max index with the resource

func TruncateBeans 

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

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

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 `xormEngine` and `xormContext` 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.

func WithTx2 

func WithTx2[T any](parentCtx context.Context, f func(ctx context.Context) (T, error)) (ret T, errRet error)

WithTx2 is similar to WithTx, but it has two return values: result and error.

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 

func (opts *AbsoluteListOptions) IsListAll() bool

IsListAll will always return false

type CheckCollationsResult 

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 

func CheckCollations(x EngineMigration) (*CheckCollationsResult, error)

func CheckCollationsDefaultEngine 

func CheckCollationsDefaultEngine() (*CheckCollationsResult, error)

type Committer 

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

Committer represents an interface to Commit or Close the Context

func TxContext 

func TxContext(parentCtx context.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.

type ConnOptions 

type ConnOptions struct {
	Type     setting.DatabaseType
	Host     string
	Database string
	User     string
	Passwd   string
	Schema   string
	SSLMode  string

	SQLitePath        string
	SQLiteBusyTimeout int
	SQLiteJournalMode string
}

func GlobalConnOptions 

func GlobalConnOptions() ConnOptions

type Engine 

type Engine interface {
	SQLSession
	Sync(...any) error
	Ping() error
}

Engine represents a xorm engine

func GetEngine 

func GetEngine(ctx context.Context) Engine

GetEngine gets an existing db Engine/Statement or creates a new Session

type EngineHook 

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

func (*EngineHook) AfterProcess 

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

func (*EngineHook) BeforeProcess 

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

type EngineMigration 

type EngineMigration interface {
	Engine
	Close() error
	DB() *core.DB
	DBMetas() ([]*schemas.Table, error)
	Dialect() dialects.Dialect
	DropTables(beans ...any) error
	NewSession() *xorm.Session
	SetMapper(mapper names.Mapper)
	SyncWithOptions(opts xorm.SyncOptions, beans ...any) (*xorm.SyncResult, error)
	TableInfo(bean any) (*schemas.Table, error)
	TableName(bean any, includeSchema ...bool) string
}

EngineMigration is a xorm engine interface used for migrations. It extends Engine with additional methods that are only available on the engine (not on the session) and are needed by the migration packages.

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 

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 

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 

func (err ErrNameReserved) Unwrap() error

Unwrap unwraps this as a ErrInvalid err

type ErrNotExist 

type ErrNotExist struct {
	Resource string
	ID       int64
}

ErrNotExist represents a non-exist error.

func (ErrNotExist) Error 

func (err ErrNotExist) Error() string

func (ErrNotExist) Unwrap 

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 

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

FindOptions represents a find options

type FindOptionsJoin 

type FindOptionsJoin interface {
	ToJoins() []JoinFunc
}

type FindOptionsOrder 

type FindOptionsOrder interface {
	ToOrders() string
}

type JoinFunc 

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 

func (opts ListOptions) GetPage() int

func (ListOptions) GetPageSize 

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 

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 

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 SQLSession 

type SQLSession interface {
	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
	FindAndCount(any, ...any) (int64, 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)
	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
	Table(tableNameOrBean any) *xorm.Session
	Context(ctx context.Context) *xorm.Session
	QueryInterface(sqlOrArgs ...any) ([]map[string]any, error)
	IsTableExist(tableNameOrBean any) (bool, error)
}

SQLSession represents a common interface for engine and session to execute SQLs

type SQLiteConnStrOptions 

type SQLiteConnStrOptions struct {
	FilePath string
	// how long a concurrent query can wait for others (milliseconds),
	// if timeout is reached, the error is something like "database is locked (SQLITE_BUSY)"
	BusyTimeout int
	JournalMode string
}

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

type Session interface {
	Engine
	And(query any, args ...any) *xorm.Session
	Begin() error
	Close() error
	Commit() error
	IsInTx() bool
	Rollback() error
	Engine() *xorm.Engine
}

Session represents a xorm session interface

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 warning 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.