refactor: use modernc sqlite driver as default (#37562)

The mattn driver is still kept, can be enabled by
TAGS="sqlite_mattn sqlite_unlock_notify"

---------

Co-authored-by: TheFox0x7 <thefox0x7@gmail.com>

models/db/conn.go

@@ -10,6 +10,7 @@ import (
 	"net/url"
 	"os"
 	"path/filepath"
+	"slices"
 	"strings"
 
 	"code.gitea.io/gitea/modules/setting"
@@ -31,7 +32,9 @@ type ConnOptions struct {
 }
 
 type SQLiteConnStrOptions struct {
-	FilePath    string
+	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
 }
@@ -52,10 +55,21 @@ func GlobalConnOptions() ConnOptions {
 	}
 }
 
-const sqlDriverPostgresSchema = "postgresschema"
+const (
+	sqlDriverPostgresSchema = "postgresschema"
+	sqlDriverSQLite3        = "sqlite3" // although database type also has "sqlite3", they are different, for different purposes
+)
 
 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`)
+	return "", "", errors.New(`this Gitea binary was not built with SQLite3 support, get an official release or rebuild with correct "-tags"`)
+}
+
+func registerSQLiteConnStrMaker(fn func(opts SQLiteConnStrOptions) (string, string, error)) {
+	if slices.Contains(setting.SupportedDatabaseTypes, setting.DatabaseTypeSQLite3) {
+		panic("another sqlite3 driver has been registered")
+	}
+	setting.SupportedDatabaseTypes = append(setting.SupportedDatabaseTypes, setting.DatabaseTypeSQLite3)
+	makeSQLiteConnStr = fn
 }
 
 func ConnStrDefaultDatabase(opts ConnOptions) (string, string, error) {

models/db/driver_sqlite_mattn.go

@@ -1,4 +1,4 @@
-//go:build sqlite
+//go:build sqlite_mattn && sqlite_unlock_notify
 
 // Copyright 2026 The Gitea Authors. All rights reserved.
 // SPDX-License-Identifier: MIT
@@ -10,14 +10,11 @@ import (
 	"strconv"
 	"strings"
 
-	"code.gitea.io/gitea/modules/setting"
-
 	_ "github.com/mattn/go-sqlite3"
 )
 
 func init() {
-	setting.SupportedDatabaseTypes = append(setting.SupportedDatabaseTypes, "sqlite3")
-	makeSQLiteConnStr = makeSQLiteConnStrMattnCGO
+	registerSQLiteConnStrMaker(makeSQLiteConnStrMattnCGO)
 }
 
 func makeSQLiteConnStrMattnCGO(opts SQLiteConnStrOptions) (string, string, error) {
@@ -30,5 +27,5 @@ func makeSQLiteConnStrMattnCGO(opts SQLiteConnStrOptions) (string, string, error
 		params = append(params, "_journal_mode="+opts.JournalMode)
 	}
 	connStr := fmt.Sprintf("file:%s?%s", opts.FilePath, strings.Join(params, "&"))
-	return "sqlite3", connStr, nil
+	return sqlDriverSQLite3, connStr, nil
 }

models/db/driver_sqlite_modernc.go

@@ -0,0 +1,41 @@
+//go:build !sqlite_mattn
+
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+// modernc driver is chosen as the default one (compared to mattn, ncruces)
+// * mattn was used as default, but it requires CGO
+// * the CI times are almost the same for these three (race detector must be disabled)
+// * modernc increases the binary size about 2MB, ncruces increases about 7MB
+// * compiling time: modernc is slightly slower than mattn, ncruces is the slowest
+
+package db
+
+import (
+	"database/sql"
+	"fmt"
+	"strings"
+
+	"modernc.org/sqlite"
+)
+
+func init() {
+	// this driver contains huge amount of Golang code, so it is much slower when "-race" check is enabled.
+	registerSQLiteConnStrMaker(makeSQLiteConnStrModerncCCGO)
+	sql.Register(sqlDriverSQLite3, &sqlite.Driver{})
+}
+
+func makeSQLiteConnStrModerncCCGO(opts SQLiteConnStrOptions) (string, string, error) {
+	var params []string
+	// TODO: there is a changed behavior from mattn driver:
+	// * mattn driver can wait for pretty long time for concurrent accesses (not limited by the busy timeout)
+	// * but other drivers will report something like "database is locked (5) (SQLITE_BUSY)" if the timeout is reached
+	// Maybe we need to relax the busy timeout to a reasonable long time in the future
+	params = append(params, fmt.Sprintf("_pragma=busy_timeout(%d)", opts.BusyTimeout))
+	params = append(params, "_txlock=immediate")
+	if opts.JournalMode != "" {
+		params = append(params, fmt.Sprintf("_pragma=journal_mode(%s)", opts.JournalMode))
+	}
+	connStr := fmt.Sprintf("file:%s?%s", opts.FilePath, strings.Join(params, "&"))
+	return sqlDriverSQLite3, connStr, nil
+}