implement basic db module

README.md

@@ -1,3 +1,3 @@
 # dbx
 
-dbx (**D**ata**b**ase **E**extensions) is a small toolkit of common and reusable database helpers built around the [Jet](https://github.com/go-jet/jet) SQL builder.
+dbx (**D**ata**b**ase **E**extensions) is a small toolkit of common and reusable database helpers built around the [Jet](https://github.com/go-jet/jet) SQL builder. Provides an [app.Module](https://gitea.auvem.com/go-toolkit/app).

config.go

@@ -0,0 +1,13 @@
+package dbx
+
+// DBConfig defines the expected structure for database configuration. Includes
+// tags for validation and maps to
+type DBConfig struct {
+	User        string `validate:"required"`
+	Password    string `validate:"required"`
+	Path        string `validate:"hostname_port,required"`
+	Name        string `validate:"required"`
+	MaxConn     int    `validate:"min=1,max=1000"`
+	AutoMigrate bool
+	DebugLog    bool
+}

db.go

@@ -0,0 +1,303 @@
+package dbx
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"reflect"
+	"slices"
+	"strings"
+
+	"gitea.auvem.com/go-toolkit/app"
+	"github.com/fatih/color"
+	"github.com/go-jet/jet/v2/mysql"
+	"github.com/go-jet/jet/v2/qrm"
+	_ "github.com/go-sql-driver/mysql"
+)
+
+// ModuleDBName is the name of the database module.
+const ModuleDBName = "database"
+
+var (
+	// ErrNoRows is returned when a query returns no rows.
+	ErrNoRows = qrm.ErrNoRows
+
+	// SQLDB stores the current SQL database handle.
+	SQLDB *sql.DB
+
+	// config stores the database connection configuration.
+	config DBConfig
+
+	// dbModule is the singleton module instance for the database connection.
+	dbModule *app.Module
+)
+
+// ModuleDB returns the database module with the provided configuration.
+func ModuleDB(cfg DBConfig, forceDebugLog bool) *app.Module {
+	if dbModule != nil {
+		panic("ModuleDB initialized multiple times")
+	}
+
+	config = cfg // store configuration at package level
+
+	if forceDebugLog {
+		config.DebugLog = true // force debug logging if requested
+	}
+
+	dbModule = app.NewModule(ModuleDBName, app.ModuleOpts{
+		Setup:    setupDB,
+		Teardown: teardownDB,
+	})
+
+	return dbModule
+}
+
+// setupDB connects to the MySQL DB and initializes the goose migration provider.
+// If auto migrations are enabled in configuration, latest migrations are applied.
+func setupDB() error {
+	if SQLDB != nil && SQLDB.Ping() == nil {
+		dbModule.Logger().Warn("Database connection already established")
+		return nil
+	}
+
+	var err error
+	db_path := fmt.Sprintf("%s:%s@tcp(%s)/%s?charset=utf8mb4&parseTime=True&loc=Local",
+		config.User, config.Password, config.Path, config.Name)
+
+	SQLDB, err = sql.Open("mysql", db_path)
+	if err != nil {
+		dbModule.Logger().Error("Couldn't open SQL database", "user", config.User, "name", config.Name, "err", err)
+		return err
+	}
+
+	if err := SQLDB.Ping(); err != nil {
+		dbModule.Logger().Error("Couldn't ping SQL database", "user", config.User, "name", config.Name, "err", err)
+		return err
+	}
+
+	SQLDB.SetMaxOpenConns(config.MaxConn)
+
+	stats := SQLDB.Stats()
+	dbModule.Logger().Info(
+		"Connected to SQL database",
+		"user", config.User,
+		"name", config.Name,
+		"path", config.Path,
+		"maxConnections", stats.MaxOpenConnections,
+		"currConnections", stats.OpenConnections,
+	)
+
+	if config.DebugLog {
+		initDBLogger()
+	}
+
+	return nil
+}
+
+// teardownDB closes the database connection.
+func teardownDB() {
+	if SQLDB == nil {
+		return
+	}
+
+	if err := SQLDB.Close(); err != nil {
+		dbModule.Logger().Error("Couldn't close database", "err", err)
+	}
+	dbModule.Logger().Info("Closed database connection")
+}
+
+// Queryable interface is an SQL driver object that can execute SQL statements
+// for Jet.
+type Queryable interface {
+	qrm.Queryable
+	Query(string, ...any) (*sql.Rows, error)
+}
+
+// Executable interface is an SQL driver object that can execute SQL statements
+// for Jet.
+type Executable interface {
+	qrm.Executable
+	Exec(string, ...any) (sql.Result, error)
+}
+
+// ExecutableTx interface is an SQL driver object that implements the Executable
+// interface and can also begin a transaction.
+type ExecutableTx interface {
+	Executable
+	Begin() (*sql.Tx, error)
+}
+
+// MustQuery executes a query and returns an error if any. Filters errors for
+// db.ErrNoRows (qrm.ErrNoRows) and returns nil or the error provided in that case.
+func MustQuery(sqlo Queryable, stmt mysql.Statement, dest any, notFoundErr error) error {
+	err := stmt.Query(sqlo, dest)
+	if err != nil {
+		if errors.Is(err, qrm.ErrNoRows) {
+			return notFoundErr
+		}
+		return err
+	}
+	return nil
+}
+
+// MustInsert requires at least one row to be affected by a query and returns the inserted ID
+func MustInsert(sqlo Executable, stmt mysql.InsertStatement) (uint64, error) {
+	res, err := stmt.Exec(sqlo)
+	if err != nil {
+		return 0, err
+	}
+
+	id, err := res.LastInsertId()
+	if err != nil {
+		return 0, err
+	}
+
+	if id < 0 {
+		return 0, fmt.Errorf("MustInsert got invalid ID: %d", id)
+	}
+
+	return uint64(id), nil
+}
+
+// MustUpdate requires at least one row to be affected by a query
+func MustUpdate(sqlo Executable, stmt mysql.Statement, notFoundErr error) error {
+	res, err := stmt.Exec(sqlo)
+	if err != nil {
+		return err
+	}
+
+	rows, err := res.RowsAffected()
+	if err != nil {
+		return err
+	}
+
+	if rows == 0 {
+		return notFoundErr
+	}
+
+	return nil
+}
+
+// MightUpdateMany expects multiple rows to be affected by a query and returns this number of rows
+func MightUpdateMany(sqlo Executable, stmt mysql.Statement) (int, error) {
+	res, err := stmt.Exec(sqlo)
+	if err != nil {
+		return 0, err
+	}
+
+	rows, err := res.RowsAffected()
+	return int(rows), err
+}
+
+// SoftDelete sets the deleted_at column to the current time
+func SoftDelete(sqlo Executable, tbl mysql.Table, conds mysql.BoolExpression) (int64, error) {
+	stmt := tbl.UPDATE().WHERE(conds)
+	query := stmt.DebugSql()
+
+	lines := strings.Split(query, "\n")
+	for i, line := range lines {
+		fmt.Println(i, line)
+	}
+
+	lines = slices.Insert(lines, 2, "SET deleted_at = NOW()")
+	query = strings.Join(lines, "\n")
+
+	res, err := sqlo.Exec(query)
+	if err != nil {
+		return 0, err
+	}
+
+	return res.RowsAffected()
+}
+
+// NormalCols processes a list of columns and strips out any that implement any of
+// mysql.ColumnTimestamp, mysql.ColumnTime, or mysql.ColumnDate
+func NormalCols(cols ...mysql.Column) mysql.ColumnList {
+	res := make(mysql.ColumnList, 0)
+
+	for _, col := range cols {
+		_, ok := col.(mysql.ColumnTimestamp)
+
+		if !ok {
+			_, ok = col.(mysql.ColumnTime)
+		}
+		if !ok {
+			_, ok = col.(mysql.ColumnDate)
+		}
+
+		if !ok {
+			res = append(res, col)
+		}
+	}
+
+	return res
+}
+
+// ContainsCol checks if a column list contains a specific column.
+func ContainsCol(cols mysql.ColumnList, col mysql.Column) bool {
+	return slices.Contains(cols, col)
+}
+
+// DestName returns the name of the type passed as `destTypeStruct` as a string,
+// normalized for compatibility with the Jet QRM.
+func DestName(destTypeStruct interface{}, path ...string) string {
+	v := reflect.ValueOf(destTypeStruct)
+	for v.Kind() == reflect.Ptr {
+		v = v.Elem()
+	}
+
+	destIdent := v.Type().String()
+	destIdent = destIdent[strings.LastIndex(destIdent, ".")+1:]
+
+	for i, p := range path {
+		if v.Kind() != reflect.Struct {
+			dbModule.Logger().Error("DestName: path parent is not a struct", "path", destIdent+"."+strings.Join(path[:i+1], "."))
+			return ""
+		}
+
+		v = v.FieldByName(p)
+
+		if !v.IsValid() {
+			dbModule.Logger().Error("DestName: field does not exist", "path", destIdent+"."+strings.Join(path[:i+1], "."))
+			return ""
+		}
+
+		destIdent += "." + p
+	}
+
+	return destIdent
+}
+
+// StringToFilter processes a string to be used as a filter in an SQL LIKE
+// statement. It replaces all spaces with % and adds % to the beginning and
+// end of the string.
+func StringToFilter(str string) string {
+	// Remove any existing leading or trailing % characters
+	str = strings.Trim(str, "%")
+
+	// Replace all spaces with % and add % to the beginning and end of the string
+	str = strings.ReplaceAll(str, " ", "%")
+	str = "%" + str + "%"
+
+	return str
+}
+
+// initDBLogger initializes the database statement logger
+func initDBLogger() {
+	mysql.SetQueryLogger(func(ctx context.Context, queryInfo mysql.QueryInfo) {
+		_, args := queryInfo.Statement.Sql()
+		dbModule.Logger().Debug(
+			"Executed SQL query",
+			"args", args,
+			"duration", queryInfo.Duration,
+			"rows", queryInfo.RowsProcessed,
+			"err", queryInfo.Err,
+		)
+
+		lines := strings.Split(queryInfo.Statement.DebugSql(), "\n")
+		for i, line := range lines {
+			fmt.Printf("%s\t%s\n", color.CyanString(fmt.Sprintf("%03d", i)), line)
+		}
+	})
+}

go.mod

@@ -1,3 +1,28 @@
 module gitea.auvem.com/go-toolkit/dbx
 
 go 1.24.0
+
+require (
+	gitea.auvem.com/go-toolkit/app v0.0.0-20250530181559-231561c92698
+	github.com/fatih/color v1.18.0
+	github.com/go-jet/jet/v2 v2.13.0
+	github.com/go-sql-driver/mysql v1.9.2
+	github.com/pressly/goose/v3 v3.24.3
+	github.com/segmentio/ksuid v1.0.4
+)
+
+require (
+	filippo.io/edwards25519 v1.1.0 // indirect
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/mattn/go-colorable v0.1.13 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/mfridman/interpolate v0.0.2 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/sethvargo/go-retry v0.3.0 // indirect
+	github.com/stretchr/testify v1.10.0 // indirect
+	go.uber.org/multierr v1.11.0 // indirect
+	golang.org/x/sync v0.14.0 // indirect
+	golang.org/x/sys v0.33.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)

go.sum

@@ -0,0 +1,61 @@
+filippo.io/edwards25519 v1.1.0 h1:FNf4tywRC1HmFuKW5xopWpigGjJKiJSV0Cqo0cJWDaA=
+filippo.io/edwards25519 v1.1.0/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4=
+gitea.auvem.com/go-toolkit/app v0.0.0-20250530181559-231561c92698 h1:Cin4hlLlcGhj05cQX1Ik6EMknzfNVGzzG8u/JnJ0uUE=
+gitea.auvem.com/go-toolkit/app v0.0.0-20250530181559-231561c92698/go.mod h1:a7ENpOxndUdONE6oZ9MZAvG1ba2uq01x/LtcnDkpOj8=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
+github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
+github.com/fatih/color v1.18.0 h1:S8gINlzdQ840/4pfAwic/ZE0djQEH3wM94VfqLTZcOM=
+github.com/fatih/color v1.18.0/go.mod h1:4FelSpRwEGDpQ12mAdzqdOukCy4u8WUtOY6lkT/6HfU=
+github.com/go-jet/jet/v2 v2.13.0 h1:DcD2IJRGos+4X40IQRV6S6q9onoOfZY/GPdvU6ImZcQ=
+github.com/go-jet/jet/v2 v2.13.0/go.mod h1:YhT75U1FoYAxFOObbQliHmXVYQeffkBKWT7ZilZ3zPc=
+github.com/go-sql-driver/mysql v1.9.2 h1:4cNKDYQ1I84SXslGddlsrMhc8k4LeDVj6Ad6WRjiHuU=
+github.com/go-sql-driver/mysql v1.9.2/go.mod h1:qn46aNg1333BRMNU69Lq93t8du/dwxI64Gl8i5p1WMU=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/mattn/go-colorable v0.1.13 h1:fFA4WZxdEF4tXPZVKMLwD8oUnCTTo08duU7wxecdEvA=
+github.com/mattn/go-colorable v0.1.13/go.mod h1:7S9/ev0klgBDR4GtXTXX8a3vIGJpMovkB8vQcUbaXHg=
+github.com/mattn/go-isatty v0.0.16/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/mfridman/interpolate v0.0.2 h1:pnuTK7MQIxxFz1Gr+rjSIx9u7qVjf5VOoM/u6BbAxPY=
+github.com/mfridman/interpolate v0.0.2/go.mod h1:p+7uk6oE07mpE/Ik1b8EckO0O4ZXiGAfshKBWLUM9Xg=
+github.com/ncruces/go-strftime v0.1.9 h1:bY0MQC28UADQmHmaF5dgpLmImcShSi2kHU9XLdhx/f4=
+github.com/ncruces/go-strftime v0.1.9/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/pressly/goose/v3 v3.24.3 h1:DSWWNwwggVUsYZ0X2VitiAa9sKuqtBfe+Jr9zFGwWlM=
+github.com/pressly/goose/v3 v3.24.3/go.mod h1:v9zYL4xdViLHCUUJh/mhjnm6JrK7Eul8AS93IxiZM4E=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
+github.com/segmentio/ksuid v1.0.4 h1:sBo2BdShXjmcugAMwjugoGUdUV0pcxY5mW4xKRn3v4c=
+github.com/segmentio/ksuid v1.0.4/go.mod h1:/XUiZBD3kVx5SmUOl55voK5yeAbBNNIed+2O73XgrPE=
+github.com/sethvargo/go-retry v0.3.0 h1:EEt31A35QhrcRZtrYFDTBg91cqZVnFL2navjDrah2SE=
+github.com/sethvargo/go-retry v0.3.0/go.mod h1:mNX17F0C/HguQMyMyJxcnU471gOZGxCLyYaFyAZraas=
+github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0=
+go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
+golang.org/x/exp v0.0.0-20250506013437-ce4c2cf36ca6 h1:y5zboxd6LQAqYIhHnB48p0ByQ/GnQx2BE33L8BOHQkI=
+golang.org/x/exp v0.0.0-20250506013437-ce4c2cf36ca6/go.mod h1:U6Lno4MTRCDY+Ba7aCcauB9T60gsv5s4ralQzP72ZoQ=
+golang.org/x/sync v0.14.0 h1:woo0S4Yywslg6hp4eUFjTVOyKt0RookbpAHG4c1HmhQ=
+golang.org/x/sync v0.14.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA=
+golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.33.0 h1:q3i8TbbEz+JRD9ywIRlyRAQbM0qF7hu24q3teo2hbuw=
+golang.org/x/sys v0.33.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+modernc.org/libc v1.65.0 h1:e183gLDnAp9VJh6gWKdTy0CThL9Pt7MfcR/0bgb7Y1Y=
+modernc.org/libc v1.65.0/go.mod h1:7m9VzGq7APssBTydds2zBcxGREwvIGpuUBaKTXdm2Qs=
+modernc.org/mathutil v1.7.1 h1:GCZVGXdaN8gTqB1Mf/usp1Y/hSqgI2vAGGP4jZMCxOU=
+modernc.org/mathutil v1.7.1/go.mod h1:4p5IwJITfppl0G4sUEDtCr4DthTaT47/N3aT6MhfgJg=
+modernc.org/memory v1.10.0 h1:fzumd51yQ1DxcOxSO+S6X7+QTuVU+n8/Aj7swYjFfC4=
+modernc.org/memory v1.10.0/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw=
+modernc.org/sqlite v1.37.0 h1:s1TMe7T3Q3ovQiK2Ouz4Jwh7dw4ZDqbebSDTlSJdfjI=
+modernc.org/sqlite v1.37.0/go.mod h1:5YiWv+YviqGMuGw4V+PNplcyaJ5v+vQd7TQOgkACoJM=