Refactor database connection (#37496)

Clean up legacy copied&pasted code, introduce the unique "database
connection" function. Move migration testing helper function
PrepareTestEnv to a separate package.

By the way, remove "shadow connection secrets" tricks: showing
connection string on UI is useless

---------

Co-authored-by: Nicolas <bircni@icloud.com>

models/db/conn.go

@@ -0,0 +1,173 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package db
+
+import (
+	"errors"
+	"fmt"
+	"net"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"code.gitea.io/gitea/modules/setting"
+	"code.gitea.io/gitea/modules/util"
+)
+
+type ConnOptions struct {
+	Type     setting.DatabaseType
+	Host     string
+	Database string
+	User     string
+	Passwd   string
+	Schema   string
+	SSLMode  string
+
+	SQLitePath        string
+	SQLiteBusyTimeout int
+	SQLiteJournalMode string
+}
+
+type SQLiteConnStrOptions struct {
+	FilePath    string
+	BusyTimeout int
+	JournalMode string
+}
+
+func GlobalConnOptions() ConnOptions {
+	return ConnOptions{
+		Type:     setting.Database.Type,
+		Host:     setting.Database.Host,
+		Database: setting.Database.Name,
+		User:     setting.Database.User,
+		Passwd:   setting.Database.Passwd,
+		Schema:   setting.Database.Schema,
+		SSLMode:  setting.Database.SSLMode,
+
+		SQLitePath:        setting.Database.Path,
+		SQLiteBusyTimeout: setting.Database.SQLiteBusyTimeout,
+		SQLiteJournalMode: setting.Database.SQLiteJournalMode,
+	}
+}
+
+const sqlDriverPostgresSchema = "postgresschema"
+
+var makeSQLiteConnStr = func(opts SQLiteConnStrOptions) (string, string, error) {
+	return "", "", errors.New(`this Gitea binary was not built with SQLite3 support, get an official release or rebuild with: -tags sqlite,sqlite_unlock_notify`)
+}
+
+func ConnStrDefaultDatabase(opts ConnOptions) (string, string, error) {
+	opts.Database, opts.Schema = "", ""
+	return ConnStr(opts)
+}
+
+func ConnStr(opts ConnOptions) (string, string, error) {
+	switch {
+	case opts.Type.IsMySQL():
+		// use unix socket or tcp socket
+		connType := util.Iif(strings.HasPrefix(opts.Host, "/"), "unix", "tcp")
+		// allow (Postgres-inspired) default value to work in MySQL
+		tls := util.Iif(opts.SSLMode == "disable", "false", opts.SSLMode)
+		// in case the database name is a partial connection string which contains "?" parameters
+		paramSep := util.Iif(strings.Contains(opts.Database, "?"), "&", "?")
+		connStr := fmt.Sprintf("%s:%s@%s(%s)/%s%sparseTime=true&tls=%s", opts.User, opts.Passwd, connType, opts.Host, opts.Database, paramSep, tls)
+		return "mysql", connStr, nil
+
+	case opts.Type.IsPostgreSQL():
+		connStr := makePgSQLConnStr(opts.Host, opts.User, opts.Passwd, opts.Database, opts.SSLMode)
+		driver := util.Iif(opts.Schema == "", "postgres", sqlDriverPostgresSchema)
+		registerPostgresSchemaDriver()
+		return driver, connStr, nil
+
+	case opts.Type.IsMSSQL():
+		host, port := parseMSSQLHostPort(opts.Host)
+		connStr := fmt.Sprintf("server=%s; port=%s; user id=%s; password=%s;", host, port, opts.User, opts.Passwd)
+		if opts.Database != "" {
+			connStr += "; database=" + opts.Database
+		}
+		return "mssql", connStr, nil
+
+	case opts.Type.IsSQLite3():
+		if opts.SQLitePath == "" {
+			return "", "", errors.New("sqlite3 database path cannot be empty")
+		}
+		if err := os.MkdirAll(filepath.Dir(opts.SQLitePath), os.ModePerm); err != nil {
+			return "", "", fmt.Errorf("failed to create directories: %w", err)
+		}
+		return makeSQLiteConnStr(SQLiteConnStrOptions{
+			FilePath:    opts.SQLitePath,
+			JournalMode: opts.SQLiteJournalMode,
+			BusyTimeout: opts.SQLiteBusyTimeout,
+		})
+	}
+	return "", "", fmt.Errorf("unknown database type: %s", opts.Type)
+}
+
+// parsePgSQLHostPort parses given input in various forms defined in
+// https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING
+// and returns proper host and port number.
+func parsePgSQLHostPort(info string) (host, port string) {
+	if h, p, err := net.SplitHostPort(info); err == nil {
+		host, port = h, p
+	} else {
+		// treat the "info" as "host", if it's an IPv6 address, remove the wrapper
+		host = info
+		if strings.HasPrefix(host, "[") && strings.HasSuffix(host, "]") {
+			host = host[1 : len(host)-1]
+		}
+	}
+
+	// set fallback values
+	if host == "" {
+		host = "127.0.0.1"
+	}
+	if port == "" {
+		port = "5432"
+	}
+	return host, port
+}
+
+func makePgSQLConnStr(dbHost, dbUser, dbPasswd, dbName, dbsslMode string) (connStr string) {
+	dbName, dbParam, _ := strings.Cut(dbName, "?")
+	host, port := parsePgSQLHostPort(dbHost)
+	connURL := url.URL{
+		Scheme:   "postgres",
+		User:     url.UserPassword(dbUser, dbPasswd),
+		Host:     net.JoinHostPort(host, port),
+		Path:     dbName,
+		OmitHost: false,
+		RawQuery: dbParam,
+	}
+	query := connURL.Query()
+	if strings.HasPrefix(host, "/") { // looks like a unix socket
+		query.Add("host", host)
+		connURL.Host = ":" + port
+	}
+	query.Set("sslmode", dbsslMode)
+	connURL.RawQuery = query.Encode()
+	return connURL.String()
+}
+
+// parseMSSQLHostPort splits the host into host and port
+func parseMSSQLHostPort(info string) (string, string) {
+	// the default port "0" might be related to MSSQL's dynamic port, maybe it should be double-confirmed in the future
+	host, port := "127.0.0.1", "0"
+	if strings.Contains(info, ":") {
+		host = strings.Split(info, ":")[0]
+		port = strings.Split(info, ":")[1]
+	} else if strings.Contains(info, ",") {
+		host = strings.Split(info, ",")[0]
+		port = strings.TrimSpace(strings.Split(info, ",")[1])
+	} else if len(info) > 0 {
+		host = info
+	}
+	if host == "" {
+		host = "127.0.0.1"
+	}
+	if port == "" {
+		port = "0"
+	}
+	return host, port
+}

models/db/conn_test.go

@@ -0,0 +1,109 @@
+// Copyright 2019 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package db
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestParsePgSQLHostPort(t *testing.T) {
+	tests := map[string]struct {
+		HostPort string
+		Host     string
+		Port     string
+	}{
+		"host-port": {
+			HostPort: "127.0.0.1:1234",
+			Host:     "127.0.0.1",
+			Port:     "1234",
+		},
+		"no-port": {
+			HostPort: "127.0.0.1",
+			Host:     "127.0.0.1",
+			Port:     "5432",
+		},
+		"ipv6-port": {
+			HostPort: "[::1]:1234",
+			Host:     "::1",
+			Port:     "1234",
+		},
+		"ipv6-no-port": {
+			HostPort: "[::1]",
+			Host:     "::1",
+			Port:     "5432",
+		},
+		"unix-socket": {
+			HostPort: "/tmp/pg.sock:1234",
+			Host:     "/tmp/pg.sock",
+			Port:     "1234",
+		},
+		"unix-socket-no-port": {
+			HostPort: "/tmp/pg.sock",
+			Host:     "/tmp/pg.sock",
+			Port:     "5432",
+		},
+	}
+	for k, test := range tests {
+		t.Run(k, func(t *testing.T) {
+			t.Log(test.HostPort)
+			host, port := parsePgSQLHostPort(test.HostPort)
+			assert.Equal(t, test.Host, host)
+			assert.Equal(t, test.Port, port)
+		})
+	}
+}
+
+func TestMakePgSQLConnStr(t *testing.T) {
+	tests := []struct {
+		Host    string
+		User    string
+		Passwd  string
+		Name    string
+		SSLMode string
+		Output  string
+	}{
+		{
+			Host:   "", // empty means default
+			Output: "postgres://:@127.0.0.1:5432?sslmode=",
+		},
+		{
+			Host:    "/tmp/pg.sock",
+			User:    "testuser",
+			Passwd:  "space space !#$%^^%^```-=?=",
+			Name:    "gitea",
+			SSLMode: "false",
+			Output:  "postgres://testuser:space%20space%20%21%23$%25%5E%5E%25%5E%60%60%60-=%3F=@:5432/gitea?host=%2Ftmp%2Fpg.sock&sslmode=false",
+		},
+		{
+			Host:    "/tmp/pg.sock:6432",
+			User:    "testuser",
+			Passwd:  "pass",
+			Name:    "gitea",
+			SSLMode: "false",
+			Output:  "postgres://testuser:pass@:6432/gitea?host=%2Ftmp%2Fpg.sock&sslmode=false",
+		},
+		{
+			Host:    "localhost",
+			User:    "pgsqlusername",
+			Passwd:  "I love Gitea!",
+			Name:    "gitea",
+			SSLMode: "true",
+			Output:  "postgres://pgsqlusername:I%20love%20Gitea%21@localhost:5432/gitea?sslmode=true",
+		},
+		{
+			Host:   "localhost:1234",
+			User:   "user",
+			Passwd: "pass",
+			Name:   "gitea?param=1",
+			Output: "postgres://user:pass@localhost:1234/gitea?param=1&sslmode=",
+		},
+	}
+
+	for _, test := range tests {
+		connStr := makePgSQLConnStr(test.Host, test.User, test.Passwd, test.Name, test.SSLMode)
+		assert.Equal(t, test.Output, connStr)
+	}
+}

models/db/driver_postgresschema.go

@@ -18,8 +18,8 @@ var registerOnce sync.Once
 
 func registerPostgresSchemaDriver() {
 	registerOnce.Do(func() {
-		sql.Register("postgresschema", &postgresSchemaDriver{})
-		dialects.RegisterDriver("postgresschema", dialects.QueryDriver("postgres"))
+		sql.Register(sqlDriverPostgresSchema, &postgresSchemaDriver{})
+		dialects.RegisterDriver(sqlDriverPostgresSchema, dialects.QueryDriver("postgres"))
 	})
 }
 

models/db/driver_sqlite_mattn.go

@@ -0,0 +1,34 @@
+//go:build sqlite
+
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package db
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+
+	"code.gitea.io/gitea/modules/setting"
+
+	_ "github.com/mattn/go-sqlite3"
+)
+
+func init() {
+	setting.SupportedDatabaseTypes = append(setting.SupportedDatabaseTypes, "sqlite3")
+	makeSQLiteConnStr = makeSQLiteConnStrMattnCGO
+}
+
+func makeSQLiteConnStrMattnCGO(opts SQLiteConnStrOptions) (string, string, error) {
+	var params []string
+	params = append(params, "cache=shared")
+	params = append(params, "mode=rwc")
+	params = append(params, "_busy_timeout="+strconv.Itoa(opts.BusyTimeout))
+	params = append(params, "_txlock=immediate")
+	if opts.JournalMode != "" {
+		params = append(params, "_journal_mode="+opts.JournalMode)
+	}
+	connStr := fmt.Sprintf("file:%s?%s", opts.FilePath, strings.Join(params, "&"))
+	return "sqlite3", connStr, nil
+}

models/db/engine_dump.go

@@ -3,10 +3,14 @@
 
 package db
 
-import "xorm.io/xorm/schemas"
+import (
+	"code.gitea.io/gitea/modules/setting"
+
+	"xorm.io/xorm/schemas"
+)
 
 // DumpDatabase dumps all data from database according the special database SQL syntax to file system.
-func DumpDatabase(filePath, dbType string) error {
+func DumpDatabase(filePath string, dbType setting.DatabaseType) error {
 	var tbs []*schemas.Table
 	for _, t := range registeredModels {
 		t, err := xormEngine.TableInfo(t)

models/db/engine_init.go

@@ -6,7 +6,6 @@ package db
 import (
 	"context"
 	"fmt"
-	"strings"
 
 	"code.gitea.io/gitea/modules/log"
 	"code.gitea.io/gitea/modules/setting"
@@ -24,31 +23,23 @@ func init() {
 
 // newXORMEngine returns a new XORM engine from the configuration
 func newXORMEngine() (*xorm.Engine, error) {
-	connStr, err := setting.DBConnStr()
+	connOpts := GlobalConnOptions()
+	driver, connStr, err := ConnStr(connOpts)
 	if err != nil {
 		return nil, err
 	}
 
-	var engine *xorm.Engine
-
-	if setting.Database.Type.IsPostgreSQL() && len(setting.Database.Schema) > 0 {
-		// OK whilst we sort out our schema issues - create a schema aware postgres
-		registerPostgresSchemaDriver()
-		engine, err = xorm.NewEngine("postgresschema", connStr)
-	} else {
-		engine, err = xorm.NewEngine(setting.Database.Type.String(), connStr)
-	}
-
+	engine, err := xorm.NewEngine(driver, connStr)
 	if err != nil {
 		return nil, err
 	}
-	switch setting.Database.Type {
-	case "mysql":
+	switch {
+	case connOpts.Type.IsMySQL():
 		engine.Dialect().SetParams(map[string]string{"rowFormat": "DYNAMIC"})
-	case "mssql":
+	case connOpts.Type.IsMSSQL():
 		engine.Dialect().SetParams(map[string]string{"DEFAULT_VARCHAR": "nvarchar"})
 	}
-	engine.SetSchema(setting.Database.Schema)
+	engine.SetSchema(connOpts.Schema)
 	return engine, nil
 }
 
@@ -56,10 +47,7 @@ func newXORMEngine() (*xorm.Engine, error) {
 func InitEngine(ctx context.Context) error {
 	xe, err := newXORMEngine()
 	if err != nil {
-		if strings.Contains(err.Error(), "SQLite3 support") {
-			return fmt.Errorf("sqlite3 requires: -tags sqlite,sqlite_unlock_notify\n%w", err)
-		}
-		return fmt.Errorf("failed to connect to database: %w", err)
+		return fmt.Errorf("failed to init database engine: %w", err)
 	}
 
 	xe.SetMapper(names.GonicMapper{})

models/db/engine_test.go

@@ -30,7 +30,7 @@ func TestDumpDatabase(t *testing.T) {
 	assert.NoError(t, db.GetEngine(t.Context()).Sync(new(Version)))
 
 	for _, dbType := range setting.SupportedDatabaseTypes {
-		assert.NoError(t, db.DumpDatabase(filepath.Join(dir, dbType+".sql"), dbType))
+		assert.NoError(t, db.DumpDatabase(filepath.Join(dir, dbType+".sql"), setting.DatabaseType(dbType)))
 	}
 }