Implement Logging

Author: kefniark

cmd/mangosql/mangosql.go

@@ -9,6 +9,7 @@ import (
 	"os"
 	"path"
 	"regexp"
+	"slices"
 	"strings"
 
 	"github.com/kefniark/mango-sql/internal"
@@ -17,40 +18,64 @@ import (
 
 func main() {
 	app := &cli.App{
+		Version:  "v0.0.1",
 		Name:     "mangosql",
 		HelpName: "MangoSQL",
 		Usage:    "Generate a SQL Client from a SQL file or folder of SQL migrations",
 		UsageText: `Syntax: mangosql [options] <source folder>
 Example: mangosql --output db/file.go db/schema.sql`,
-		Suggest: true,
+		Suggest:              true,
+		EnableBashCompletion: true,
 		Flags: []cli.Flag{
 			&cli.StringFlag{
-				Name:  "output",
-				Value: "database/client.go",
-				Usage: "Output file",
+				Name:    "output",
+				Aliases: []string{"o"},
+				Value:   "database/client.go",
+				Usage:   "Output file",
 			},
 			&cli.StringFlag{
-				Name:  "package",
-				Value: "database",
-				Usage: "Go Package",
+				Name:    "package",
+				Aliases: []string{"p"},
+				Value:   "database",
+				Usage:   "Go Package",
 			},
 			&cli.StringFlag{
-				Name:  "driver",
-				Value: "pgx",
-				Usage: "SQL Driver",
+				Name:    "driver",
+				Aliases: []string{"d"},
+				Value:   "pgx",
+				Usage:   "SQL Driver",
+			},
+			&cli.StringFlag{
+				Name:    "logger",
+				Aliases: []string{"l"},
+				Value:   "none",
+				Usage:   "Logging library",
 			},
 		},
 		Action: func(ctx *cli.Context) error {
 			if ctx.NArg() <= 0 {
 				return fmt.Errorf("missing source folder")
 			}
 
+			allowed_drivers := []string{"pq", "pgx", "sqlite"}
+			driver := ctx.String("driver")
+			if !slices.Contains(allowed_drivers, driver) {
+				return fmt.Errorf("unknown driver, should be one of %v", allowed_drivers)
+			}
+
+			allowed_logger := []string{"none", "zap", "logrus", "zerolog", "console"}
+			logger := ctx.String("logger")
+			if !slices.Contains(allowed_logger, logger) {
+				return fmt.Errorf("unknown logger, should be one of %v", allowed_logger)
+			}
+
 			name := ctx.Args().Get(0)
 			return generate(GenerateOptions{
 				Src:     name,
 				Output:  ctx.String("output"),
 				Package: ctx.String("package"),
-				Driver:  ctx.String("driver"),
+				Driver:  driver,
+				Logger:  logger,
 			})
 		},
 	}
@@ -65,6 +90,7 @@ type GenerateOptions struct {
 	Output  string
 	Package string
 	Driver  string
+	Logger  string
 }
 
 func generate(opts GenerateOptions) error {
@@ -110,7 +136,7 @@ func generate(opts GenerateOptions) error {
 	var b bytes.Buffer
 	contents := bufio.NewWriter(&b)
 
-	if err = internal.Generate(schema, contents, opts.Package, opts.Driver); err != nil {
+	if err = internal.Generate(schema, contents, opts.Package, opts.Driver, opts.Logger); err != nil {
 		return err
 	}
 

docs/.vitepress/config.mts

@@ -34,7 +34,7 @@ export default defineConfig({
         items: [
           // { text: 'UUID Generation', link: '/api/mutations' },
           { text: 'Soft Delete', link: '/features/soft-delete' },
-          // { text: 'Logging', link: '/api/mutations' },
+          { text: 'Logging', link: '/features/logging' },
           // { text: 'Migrations', link: '/api/mutations' },
         ]
       },

docs/features/logging.md

@@ -0,0 +1,110 @@
+# Logging
+
+MangoSQL has integration for common Go loggers, this make working with SQL queries easier.
+
+This logging feature is opt-in and comes with:
+* Every Query will emit a **Debug** log
+  * With the function name
+  * With duration measurements
+  * With SQL Query and arguments
+* **warning** for slow queries, when a query takes more than >500ms
+* Every SQL error will be automatically logged as **error**
+
+::: tips
+
+    During development, we recommend to set the log level to `DebugLevel` to see the SQL queries generated and how long they take.
+
+:::
+
+## Logrus (https://github.com/sirupsen/logrus) { #logrus }
+
+Add `--logger logrus` to the cli command
+
+```sh
+mangosql --logger logrus ./schema.sql
+```
+
+And provide the logger to MangoSQL Client at initialization.
+
+```go
+package database
+
+import (
+    // ...
+    "github.com/sirupsen/logrus"
+)
+
+// create your own logger instance
+logger := logrus.New()
+
+// instantiate DBClient
+return New(db, logger)
+```
+
+## Zap (https://github.com/uber-go/zap) { #zap }
+
+Add `--logger zap` to the cli command
+
+```sh
+mangosql --logger zap ./schema.sql
+```
+
+And provide the logger to MangoSQL Client at initialization.
+
+```go
+package database
+
+import (
+    // ...
+    "go.uber.org/zap"
+)
+
+// create your own logger instance
+logger, _ := zap.NewProduction()
+
+// instantiate DBClient
+return New(db, logger)
+```
+
+## Zerolog (https://github.com/rs/zerolog) { #zerolog }
+
+Add `--logger zerolog` to the cli command
+
+```sh
+mangosql --logger zerolog ./schema.sql
+```
+
+And provide the logger to MangoSQL Client at initialization.
+
+```go
+package database
+
+import (
+    // ...
+    "github.com/rs/zerolog"
+)
+
+// create your own logger instance
+logger := zerolog.New(os.Stderr).With().Timestamp().Logger()
+
+// instantiate DBClient
+return New(db, logger)
+```
+
+## Testing / Console
+
+This logger option is a bit special, this is a console writer intended for development and testing only.
+It's literally just calling `log.Println()`, has colors and is zero configuration.
+
+Add `--logger console` to the cli command and you have nothing else to modify in your code.
+
+```sh
+mangosql --logger console ./schema.sql
+```
+
+The output will looks like this
+```logs
+2024/08/20 04:32:46 [DEBUG] DB.User.FindMany  308.236µs
+   | Args: [[1]]
+   | SQL: SELECT id, name, created_at, deleted_at FROM users WHERE id = $1 LIMIT 1 OFFSET 0
+```

internal/database/database.go

@@ -31,7 +31,7 @@ var customTypes = []FieldInitializer{
 	},
 }
 
-func Generate(schema *core.SQLSchema, contents io.Writer, pkg string, driver string) error {
+func Generate(schema *core.SQLSchema, contents io.Writer, pkg string, driver string, logger string) error {
 	templateType := ""
 	switch driver {
 	case "pgx":
@@ -50,6 +50,11 @@ func Generate(schema *core.SQLSchema, contents io.Writer, pkg string, driver str
 		return err
 	}
 
+	loggerTmpl, err := template.ParseFS(templates, fmt.Sprintf("templates/logger_%s.tmpl", logger))
+	if err != nil {
+		return err
+	}
+
 	modelTmpl, err := template.ParseFS(templates, "templates/model.tmpl")
 	if err != nil {
 		return err
@@ -110,6 +115,38 @@ func Generate(schema *core.SQLSchema, contents io.Writer, pkg string, driver str
 		placeholder = "squirrel.Question"
 	}
 
+	logConfig := LoggerConfig{}
+
+	switch logger {
+	case "zap":
+		deps["zap"] = "go.uber.org/zap"
+		deps["time"] = "time"
+		logConfig.HasLogger = true
+		logConfig.HasLoggerParam = true
+		logConfig.Type = `*zap.Logger`
+	case "logrus":
+		deps["logrus"] = "github.com/sirupsen/logrus"
+		deps["time"] = "time"
+		logConfig.HasLogger = true
+		logConfig.HasLoggerParam = true
+		logConfig.Type = `*logrus.Logger`
+	case "zerolog":
+		deps["zero"] = "github.com/rs/zerolog"
+		deps["time"] = "time"
+		logConfig.HasLogger = true
+		logConfig.HasLoggerParam = true
+		logConfig.Type = `zerolog.Logger`
+	case "console":
+		deps["log"] = "log"
+		deps["time"] = "time"
+
+		logConfig.HasLogger = true
+		logConfig.HasLoggerParam = false
+		logConfig.Type = ``
+	}
+
+	fmt.Println(logger, logConfig)
+
 	if err = headerTmpl.Execute(contents, HeaderData{
 		Package:     pkg,
 		Url:         "https://github.com/kefniark/mangosql",
@@ -125,25 +162,49 @@ func Generate(schema *core.SQLSchema, contents io.Writer, pkg string, driver str
 		Tables  []*PostgresTable
 		Queries []*PostgresQuery
 		Filters []FilterMethod
+		Logger  LoggerConfig
 	}{
 		Tables:  postgresTables,
 		Queries: postgresQueries,
 		Filters: GetFilterMethods(postgresTables, driver),
+		Logger:  logConfig,
 	}); err != nil {
 		return err
 	}
 
+	if err = loggerTmpl.Execute(contents, nil); err != nil {
+		return err
+	}
+
 	for _, table := range postgresTables {
-		if err = modelTmpl.Execute(contents, table); err != nil {
+		if err = modelTmpl.Execute(contents, struct {
+			Table  *PostgresTable
+			Logger LoggerConfig
+		}{
+			Table:  table,
+			Logger: logConfig,
+		}); err != nil {
 			return err
 		}
 
-		if err = queriesTmpl.Execute(contents, table); err != nil {
+		if err = queriesTmpl.Execute(contents, struct {
+			Table  *PostgresTable
+			Logger LoggerConfig
+		}{
+			Table:  table,
+			Logger: logConfig,
+		}); err != nil {
 			return err
 		}
 	}
 
-	if err = customQueriesTmpl.Execute(contents, postgresQueries); err != nil {
+	if err = customQueriesTmpl.Execute(contents, struct {
+		Queries []*PostgresQuery
+		Logger  LoggerConfig
+	}{
+		Queries: postgresQueries,
+		Logger:  logConfig,
+	}); err != nil {
 		return err
 	}
 
@@ -789,3 +850,9 @@ type PrimaryFieldInit struct {
 	Init   string
 	Setter string
 }
+
+type LoggerConfig struct {
+	HasLoggerParam bool
+	HasLogger      bool
+	Type           string
+}

internal/database/templates/custom.tmpl

@@ -1,16 +1,16 @@
-{{ if len . }}
+{{ if len .Queries }}
 type CustomQueries struct {
 	ctx *DBContext
 }
 
-{{ range . }}
+{{ range .Queries }}
     // Find {{ .NameNormalized }} records based on the provided conditions
     //
     // Usage:
     //   entities, err := db.Queries.{{ .NameNormalized }}(
     //     // ... can use filters here (cf db.{{ .NameNormalized }}.Query.*)
     //   )
-    func (q *CustomQueries) {{ .NameNormalized }}(filters ...WhereCondition) ([]{{ .NameNormalized }}Model, error ) {
+    func (q *CustomQueries) {{ .NameNormalized }}(filters ...WhereCondition) (requestData []{{ .NameNormalized }}Model, requestErr error ) {
         query := squirrel.Select("{{ .Select }}")
         query = query.From("{{ .From }}").PlaceholderFormat(placeholder)
 {{ if .Where }}        query = query.Where("{{ .Where }}")
@@ -23,7 +23,11 @@ type CustomQueries struct {
         sql, args, err := query.ToSql()
         if err != nil {
             return nil, err
-        }
+        }{{ if $.Logger.HasLogger }}
+        start := time.Now()
+        defer func() {
+            q.ctx.logQuery(Debug, "DB.Queries.{{ .NameNormalized }}", requestErr, time.Since(start), sql, args)
+        }(){{ end }}
 
         return QueryMany[{{ .NameNormalized }}Model](q.ctx, sql, args...)
     }