diff --git a/README.md b/README.md index b58d59a..fe22862 100644 --- a/README.md +++ b/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). diff --git a/config.go b/config.go new file mode 100644 index 0000000..68f8e4a --- /dev/null +++ b/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 +} diff --git a/db.go b/db.go new file mode 100644 index 0000000..91be634 --- /dev/null +++ b/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) + } + }) +} diff --git a/go.mod b/go.mod index 1356d25..d2ad522 100644 --- a/go.mod +++ b/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 +) diff --git a/go.sum b/go.sum new file mode 100644 index 0000000..4ce389e --- /dev/null +++ b/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=