chore(db): introduce db.Session and db.EngineMigration interfaces (#37746)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: wxiaoguang <2114189+wxiaoguang@users.noreply.github.com>
Co-authored-by: wxiaoguang <wxiaoguang@gmail.com>

models/db/collation.go

@@ -12,7 +12,6 @@ import (
 	"code.gitea.io/gitea/modules/log"
 	"code.gitea.io/gitea/modules/setting"
 
-	"xorm.io/xorm"
 	"xorm.io/xorm/schemas"
 )
 
@@ -27,7 +26,7 @@ type CheckCollationsResult struct {
 	InconsistentCollationColumns []string
 }
 
-func findAvailableCollationsMySQL(x *xorm.Engine) (ret container.Set[string], err error) {
+func findAvailableCollationsMySQL(x EngineMigration) (ret container.Set[string], err error) {
 	var res []struct {
 		Collation string
 	}
@@ -41,7 +40,7 @@ func findAvailableCollationsMySQL(x *xorm.Engine) (ret container.Set[string], er
 	return ret, nil
 }
 
-func findAvailableCollationsMSSQL(x *xorm.Engine) (ret container.Set[string], err error) {
+func findAvailableCollationsMSSQL(x EngineMigration) (ret container.Set[string], err error) {
 	var res []struct {
 		Name string
 	}
@@ -55,7 +54,7 @@ func findAvailableCollationsMSSQL(x *xorm.Engine) (ret container.Set[string], er
 	return ret, nil
 }
 
-func CheckCollations(x *xorm.Engine) (*CheckCollationsResult, error) {
+func CheckCollations(x EngineMigration) (*CheckCollationsResult, error) {
 	dbTables, err := x.DBMetas()
 	if err != nil {
 		return nil, err
@@ -143,7 +142,7 @@ func CheckCollationsDefaultEngine() (*CheckCollationsResult, error) {
 	return CheckCollations(xormEngine)
 }
 
-func alterDatabaseCollation(x *xorm.Engine, collation string) error {
+func alterDatabaseCollation(x EngineMigration, collation string) error {
 	if x.Dialect().URI().DBType == schemas.MYSQL {
 		_, err := x.Exec("ALTER DATABASE CHARACTER SET utf8mb4 COLLATE " + collation)
 		return err
@@ -156,7 +155,7 @@ func alterDatabaseCollation(x *xorm.Engine, collation string) error {
 }
 
 // preprocessDatabaseCollation checks database & table column collation, and alter the database collation if needed
-func preprocessDatabaseCollation(x *xorm.Engine) {
+func preprocessDatabaseCollation(x EngineMigration) {
 	r, err := CheckCollations(x)
 	if err != nil {
 		log.Error("Failed to check database collation: %v", err)

models/db/engine.go

@@ -16,6 +16,10 @@ import (
 	_ "github.com/microsoft/go-mssqldb" // Needed for the MSSQL driver
 
 	"xorm.io/xorm"
+	"xorm.io/xorm/core"
+	"xorm.io/xorm/dialects"
+	"xorm.io/xorm/names"
+	"xorm.io/xorm/schemas"
 )
 
 var (
@@ -33,6 +37,7 @@ type Engine interface {
 	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
@@ -61,9 +66,41 @@ type Engine interface {
 	IsTableExist(tableNameOrBean any) (bool, error)
 }
 
+// Session represents a xorm session interface, used as an abstraction over *xorm.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
+}
+
+// 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 EngineMigration interface {
+	Engine
+	Close() error
+	DB() *core.DB
+	DBMetas() ([]*schemas.Table, error)
+	Dialect() dialects.Dialect
+	DropTables(beans ...any) error
+	NewSession() *xorm.Session
+	QueryInterface(sqlOrArgs ...any) ([]map[string]any, error)
+	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
+}
+
 var (
-	_ Engine = (*xorm.Engine)(nil)
-	_ Engine = (*xorm.Session)(nil)
+	_ Engine          = (*xorm.Engine)(nil)
+	_ Engine          = (*xorm.Session)(nil)
+	_ Session         = (*xorm.Session)(nil)
+	_ EngineMigration = (*xorm.Engine)(nil)
 )
 
 // RegisterModel registers model, if initFuncs provided, it will be invoked after data model sync

models/db/engine_init.go

@@ -92,7 +92,7 @@ func UnsetDefaultEngine() {
 // 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 InitEngineWithMigration(ctx context.Context, migrateFunc func(context.Context, *xorm.Engine) error) (err error) {
+func InitEngineWithMigration(ctx context.Context, migrateFunc func(context.Context, EngineMigration) error) (err error) {
 	if err = InitEngine(ctx); err != nil {
 		return err
 	}

models/db/list.go

@@ -9,7 +9,6 @@ import (
 	"code.gitea.io/gitea/modules/setting"
 
 	"xorm.io/builder"
-	"xorm.io/xorm"
 )
 
 const (
@@ -25,7 +24,7 @@ type Paginator interface {
 }
 
 // SetSessionPagination sets pagination for a database session
-func SetSessionPagination(sess Engine, p Paginator) *xorm.Session {
+func SetSessionPagination(sess Engine, p Paginator) Session {
 	skip, take := p.GetSkipTake()
 
 	return sess.Limit(take, skip)