Add function "AddToCommandFlags" to FlagValidator interface

Signed-off-by: Jan Tytgat <jan.tytgat@corelayer.eu>

.gitea/workflows/push.yaml

@@ -0,0 +1,9 @@
+name: Gitea Actions Demo
+run-name: ${{ gitea.actor }} is testing out Gitea Actions 🚀
+on: [push]
+
+jobs:
+  Explore-Gitea-Actions:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "The job was automatically triggered by a ${{ gitea.event_name }} event."

.gitignore

@@ -25,3 +25,6 @@ go.work.sum
 # env file
 .env
 
+
+.idea
+

application/application.go

@@ -0,0 +1,107 @@
+package application
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"os/signal"
+
+	"github.com/spf13/cobra"
+
+	"git.flexabyte.io/flexabyte/go-kit/slogd"
+)
+
+type Application interface {
+	ExecuteContext(ctx context.Context) error
+}
+
+func New(c Config) (Application, error) {
+	var cmd *cobra.Command
+	var err error
+	if cmd, err = c.getRootCommand(); err != nil {
+		return nil, err
+	}
+
+	return &application{
+		cmd:    cmd,
+		config: c,
+	}, nil
+}
+
+type application struct {
+	cmd    *cobra.Command
+	config Config
+}
+
+func (a *application) ExecuteContext(ctx context.Context) error {
+	a.config.Logger.LogAttrs(ctx, slogd.LevelTrace, "configuring application shutdown signals", slog.Any("signals", a.config.ShutdownSignals))
+
+	sigCtx, sigCancel := signal.NotifyContext(ctx, a.config.ShutdownSignals...)
+	defer sigCancel() // Ensure that this gets called.
+
+	// Result channel for command output
+	chExe := make(chan error)
+
+	// Run the application command using the signal context and output channel
+	a.config.Logger.LogAttrs(ctx, slogd.LevelTrace, "executing application context")
+	go func(ctx context.Context, chErr chan error) {
+		chErr <- a.cmd.ExecuteContext(ctx)
+	}(sigCtx, chExe)
+
+	// Wait for command output or a shutdown signal
+	select {
+	case <-sigCtx.Done(): // sigCtx.Done() returns a channel that will have a message when the context is canceled.
+		sigCancel()
+		return a.handleShutdownSignal(ctx)
+	case err := <-chExe: // Alternatively, chExe will receive the response from the execution context if the application finishes.
+		a.config.Logger.LogAttrs(ctx, slogd.LevelTrace, "application terminated successfully")
+		return err
+	}
+}
+
+func (a *application) gracefulShutdown(ctx context.Context) error {
+	fmt.Printf("waiting %s for graceful application shutdown... PRESS CTRL+C again to quit now!\n", a.config.ShutdownTimeout)
+
+	shutdownCtx, shutdownCancel := context.WithTimeout(ctx, a.config.ShutdownTimeout)
+	defer shutdownCancel()
+
+	// Wait for the shutdown timeout or a hard exit signal
+	sigCtx, sigCancel := signal.NotifyContext(shutdownCtx, a.config.ShutdownSignals...)
+	defer sigCancel() // Ensure that this gets called.
+
+	select {
+	case <-shutdownCtx.Done(): // Timeout exceeded
+		return shutdownCtx.Err()
+	case <-sigCtx.Done(): // Received additional shutdown signal to forcefully exit
+		fmt.Println("exiting...")
+		sigCancel()
+		return fmt.Errorf("process killed")
+	}
+}
+
+func (a *application) handleGracefulShutdown(ctx context.Context) error {
+	a.config.Logger.LogAttrs(ctx, slogd.LevelTrace, "gracefully shutting down application")
+
+	var err error
+	if err = a.gracefulShutdown(ctx); !errors.Is(err, context.DeadlineExceeded) {
+		a.config.Logger.LogAttrs(ctx, slogd.LevelWarn, "graceful shutdown failed", slog.Any("error", err))
+		return nil
+	}
+
+	a.config.Logger.LogAttrs(ctx, slogd.LevelTrace, "graceful shutdown completed")
+	return nil
+}
+
+func (a *application) handleShutdownSignal(ctx context.Context) error {
+	// Adapt the shutdown scenario if a graceful shutdown period is configured
+	switch a.config.EnableGracefulShutdown && a.config.ShutdownTimeout > 0 {
+	case true:
+		return a.handleGracefulShutdown(ctx)
+	case false:
+		a.config.Logger.LogAttrs(ctx, slogd.LevelTrace, "immediately shutting down application")
+		return nil
+	default:
+		panic("cannot handle shutdown signal")
+	}
+}

application/application_test.go

@@ -0,0 +1 @@
+package application

application/commander.go

@@ -0,0 +1,28 @@
+package application
+
+import "github.com/spf13/cobra"
+
+type Commander interface {
+	Initialize(f func(c *cobra.Command)) *cobra.Command
+}
+
+type Command struct {
+	Command     *cobra.Command
+	SubCommands []Commander
+	Configure   func(c *cobra.Command)
+}
+
+func (c Command) Initialize(f func(cmd *cobra.Command)) *cobra.Command {
+	if f != nil {
+		f(c.Command)
+	}
+
+	if c.Configure != nil {
+		c.Configure(c.Command)
+	}
+
+	for _, sub := range c.SubCommands {
+		c.Command.AddCommand(sub.Initialize(f))
+	}
+	return c.Command
+}

application/config.go

@@ -0,0 +1,104 @@
+package application
+
+import (
+	"errors"
+	"fmt"
+	"log/slog"
+	"os"
+	"time"
+
+	"github.com/spf13/cobra"
+)
+
+type Config struct {
+	Name                     string
+	Title                    string
+	Banner                   string
+	Version                  Version
+	EnableGracefulShutdown   bool
+	Logger                   *slog.Logger
+	OverrideRunE             func(cmd *cobra.Command, args []string) error
+	PersistentPreRunE        []func(cmd *cobra.Command, args []string) error // collection of PreRunE functions
+	PersistentPostRunE       []func(cmd *cobra.Command, args []string) error // collection of PostRunE functions
+	ShutdownSignals          []os.Signal
+	ShutdownTimeout          time.Duration
+	SubCommands              []Commander
+	SubCommandInitializeFunc func(cmd *cobra.Command)
+	ValidArgs                []string
+}
+
+func (c Config) getRootCommand() (*cobra.Command, error) {
+	var err error
+	if err = c.Validate(); err != nil {
+		return nil, err
+	}
+
+	var long string
+	if c.Banner != "" {
+		long = c.Banner + "\n" + c.Title
+	} else {
+		long = c.Title
+	}
+
+	cmd := &cobra.Command{
+		Use:                c.Name,
+		Short:              c.Title,
+		Long:               long,
+		PersistentPreRunE:  persistentPreRunFuncE,
+		PersistentPostRunE: persistentPostRunFuncE,
+		RunE:               RunCatchFuncE,
+		SilenceErrors:      true,
+		SilenceUsage:       true,
+	}
+
+	if c.OverrideRunE != nil {
+		cmd.RunE = c.OverrideRunE
+	}
+
+	for _, subcommand := range c.SubCommands {
+		cmd.AddCommand(subcommand.Initialize(c.SubCommandInitializeFunc))
+	}
+
+	configureVersionFlag(cmd, c.Version)                  // Configure app for version information
+	configureOutputFlags(cmd)                             // Configure verbosity
+	configureLoggingFlags(cmd)                            // Configure logging
+	cmd.PersistentFlags().SetNormalizeFunc(normalizeFunc) // normalize persistent flags
+
+	return cmd, nil
+}
+
+func (c Config) RegisterCommand(cmd Commander, f func(*cobra.Command)) {
+	appCmd.AddCommand(cmd.Initialize(f))
+}
+
+func (c Config) RegisterCommands(cmds []Commander, f func(*cobra.Command)) {
+	for _, cmd := range cmds {
+		appCmd.AddCommand(cmd.Initialize(f))
+	}
+}
+
+func (c Config) RegisterPersistentPreRunE(f func(cmd *cobra.Command, args []string) error) {
+	persistentPreRunE = append(persistentPreRunE, f)
+}
+
+func (c Config) RegisterPersistentPostRunE(f func(cmd *cobra.Command, args []string) error) {
+	persistentPostRunE = append(persistentPostRunE, f)
+}
+
+func (c Config) Validate() error {
+	if c.Name == "" {
+		return errors.New("name is required")
+	}
+	if c.Title == "" {
+		return errors.New("title is required")
+	}
+
+	if c.Logger == nil {
+		return errors.New("logger is required")
+	}
+
+	if !c.Version.IsValid() {
+		return fmt.Errorf("invalid version: %s", c.Version)
+	}
+	return nil
+}

application/config_test.go

@@ -0,0 +1,22 @@
+package application
+
+import (
+	"testing"
+)
+
+func TestConfig_Validate(t *testing.T) {
+	tests := []struct {
+		name    string
+		config  Config
+		wantErr bool
+	}{
+		{},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if err := tt.config.Validate(); (err != nil) != tt.wantErr {
+				t.Errorf("Validate() error = %v, wantErr %v", err, tt.wantErr)
+			}
+		})
+	}
+}

application/globals.go

@@ -0,0 +1,108 @@
+package application
+
+import (
+	"fmt"
+	"io"
+	"log/slog"
+	"os"
+	"reflect"
+	"runtime"
+	"strings"
+	"syscall"
+
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+
+	"git.flexabyte.io/flexabyte/go-kit/slogd"
+)
+
+var DefaultShutdownSignals = []os.Signal{syscall.SIGINT, syscall.SIGTERM, syscall.SIGHUP, syscall.SIGQUIT}
+
+var (
+	appName            string
+	appCmd             *cobra.Command
+	persistentPreRunE  []func(cmd *cobra.Command, args []string) error // collection of PreRunE functions
+	persistentPostRunE []func(cmd *cobra.Command, args []string) error // collection of PostRunE functions
+	outWriter          io.Writer                                       = os.Stdout
+)
+
+func SubCommandInitializePrintNameFunc(cmd *cobra.Command) {
+	fmt.Println("Initializing:", cmd.Name())
+}
+
+func HelpFuncE(cmd *cobra.Command, args []string) error {
+	return cmd.Help()
+}
+
+func normalizeFunc(f *pflag.FlagSet, name string) pflag.NormalizedName {
+	return pflag.NormalizedName(name)
+}
+
+func persistentPreRunFuncE(cmd *cobra.Command, args []string) error {
+	slogd.SetLevel(slogd.Level(logLevelFlag.Value))
+
+	if slogd.ActiveHandler() != slogd.HandlerJSON && noColorFlag.Value {
+		slogd.UseHandler(slogd.HandlerText)
+		cmd.SetContext(slogd.WithContext(cmd.Context()))
+	}
+
+	slogd.FromContext(cmd.Context()).Log(cmd.Context(), slogd.LevelTrace, "starting application", slog.String("command", cmd.CommandPath()))
+	slogd.FromContext(cmd.Context()).Log(cmd.Context(), slogd.LevelTrace, "executing PersistentPreRun")
+
+	// Make sure we can always get the version
+	if versionFlag.Value || cmd.CommandPath() == strings.Join([]string{appName, versionFlagName}, " ") {
+		slogd.FromContext(cmd.Context()).LogAttrs(cmd.Context(), slogd.LevelTrace, "overriding command", slog.String("old_function", runtime.FuncForPC(reflect.ValueOf(cmd.RunE).Pointer()).Name()), slog.String("new_function", runtime.FuncForPC(reflect.ValueOf(versionRunFuncE).Pointer()).Name()))
+		cmd.RunE = versionRunFuncE
+		return nil
+	}
+
+	// Make sure that we show the app help if no commands or flags are passed
+	if cmd.CalledAs() == appName && runtime.FuncForPC(reflect.ValueOf(cmd.RunE).Pointer()).Name() == runtime.FuncForPC(reflect.ValueOf(RunCatchFuncE).Pointer()).Name() {
+		slogd.FromContext(cmd.Context()).LogAttrs(cmd.Context(), slogd.LevelTrace, "overriding command", slog.String("old_function", runtime.FuncForPC(reflect.ValueOf(cmd.RunE).Pointer()).Name()), slog.String("new_function", runtime.FuncForPC(reflect.ValueOf(HelpFuncE).Pointer()).Name()))
+
+		cmd.RunE = HelpFuncE
+		return nil
+	}
+
+	// TODO move to front??
+	if quietFlag.Value {
+		slogd.FromContext(cmd.Context()).LogAttrs(cmd.Context(), slogd.LevelTrace, "activating quiet mode")
+		outWriter = io.Discard
+	}
+
+	if persistentPreRunE == nil {
+		return nil
+	}
+
+	var err error
+	for _, preRun := range persistentPreRunE {
+		slogd.FromContext(cmd.Context()).Log(cmd.Context(), slogd.LevelTrace, "executing PersistentPreRun function", slog.String("function", runtime.FuncForPC(reflect.ValueOf(preRun).Pointer()).Name()))
+		if err = preRun(cmd, args); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func persistentPostRunFuncE(cmd *cobra.Command, args []string) error {
+	defer slogd.FromContext(cmd.Context()).Log(cmd.Context(), slogd.LevelTrace, "stopping application", slog.String("command", cmd.CommandPath()))
+	slogd.FromContext(cmd.Context()).Log(cmd.Context(), slogd.LevelTrace, "executing PersistentPostRunE")
+
+	if persistentPostRunE == nil {
+		return nil
+	}
+
+	var err error
+	for _, postRun := range persistentPostRunE {
+		slogd.FromContext(cmd.Context()).Log(cmd.Context(), slogd.LevelTrace, "executing PersistentPostRun function", slog.String("function", runtime.FuncForPC(reflect.ValueOf(postRun).Pointer()).Name()))
+		if err = postRun(cmd, args); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// RunCatchFuncE is an empty catch function to allow overrides through persistentPreRunE
+func RunCatchFuncE(cmd *cobra.Command, args []string) error {
+	return nil
+}

application/logging.go

@@ -0,0 +1,62 @@
+package application
+
+import (
+	"fmt"
+	"log/slog"
+
+	"github.com/Oudwins/zog"
+	"github.com/spf13/cobra"
+
+	"git.flexabyte.io/flexabyte/go-kit/flagzog"
+	"git.flexabyte.io/flexabyte/go-kit/slogd"
+)
+
+const (
+	logLevelTrace   = "trace"
+	logLevelDebug   = "debug"
+	logLevelInfo    = "info"
+	logLevelWarn    = "warn"
+	logLevelError   = "error"
+	logLevelFatal   = "fatal"
+	logOutputStdout = "stdout"
+	logOutputStderr = "stderr"
+	logOutputFile   = "file"
+	logTypeText     = "text"
+	logTypeJson     = "json"
+	logTypeColor    = "color"
+)
+
+var (
+	logLevelFlag  = flagzog.NewStringFlag("log-level", zog.String().OneOf([]string{logLevelTrace, logLevelDebug, logLevelInfo, logLevelWarn, logLevelError, logLevelFatal}), fmt.Sprintf("Set log level (%s, %s, %s, %s, %s, %s)", logLevelTrace, logLevelDebug, logLevelInfo, logLevelWarn, logLevelError, logLevelFatal))
+	logOutputFlag = flagzog.NewStringFlag("log-output", zog.String().OneOf([]string{logOutputStdout, logOutputStderr, logOutputFile}), fmt.Sprintf("Set log output (%s, %s, %s)", logOutputStdout, logOutputStderr, logOutputFile))
+	logTypeFlag   = flagzog.NewStringFlag("log-type", zog.String().OneOf([]string{logTypeText, logTypeJson, logTypeColor}), fmt.Sprintf("Set log type (%s, %s, %s)", logTypeText, logTypeJson, logTypeColor))
+)
+
+func addLogLevelFlag(cmd *cobra.Command) {
+	cmd.PersistentFlags().StringVarP(&logLevelFlag.Value, logLevelFlag.Name(), "", logLevelInfo, logLevelFlag.Usage())
+}
+
+func addLogOutputFlag(cmd *cobra.Command) {
+	cmd.PersistentFlags().StringVarP(&logOutputFlag.Value, logOutputFlag.Name(), "", logOutputStderr, logOutputFlag.Usage())
+}
+
+func addLogTypeFlag(cmd *cobra.Command) {
+	cmd.PersistentFlags().StringVarP(&logTypeFlag.Value, logTypeFlag.Name(), "", logTypeText, logTypeFlag.Usage())
+}
+
+func configureLoggingFlags(cmd *cobra.Command) {
+	addLogLevelFlag(cmd)
+	addLogOutputFlag(cmd)
+	addLogTypeFlag(cmd)
+
+	cmd.MarkFlagsMutuallyExclusive("no-color", logTypeFlag.Name())
+}
+
+func GetLogLevelFromArgs(args []string) slog.Level {
+	for i, arg := range args {
+		if arg == "--log-level" && i+1 < len(args) {
+			return slogd.Level(args[i+1])
+		}
+	}
+	return slogd.LevelDefault
+}

application/output.go

@@ -0,0 +1,51 @@
+package application
+
+import (
+	"github.com/Oudwins/zog"
+	"github.com/spf13/cobra"
+
+	"git.flexabyte.io/flexabyte/go-kit/flagzog"
+)
+
+const (
+	jsonOutputFlagDefault = false
+	noColorFlagDefault    = false
+	quietFlagDefault      = false
+	quietFlagShortCode    = "q"
+	verboseFlagDefault    = false
+	verboseFlagShortCode  = "v"
+)
+
+var (
+	jsonOutputFlag = flagzog.NewBoolFlag("json", zog.Bool(), "Enable JSON output")
+	noColorFlag    = flagzog.NewBoolFlag("no-color", zog.Bool(), "Disable colored output")
+	quietFlag      = flagzog.NewBoolFlag("quiet", zog.Bool(), "Suppress output")
+	verboseFlag    = flagzog.NewBoolFlag("verbose", zog.Bool(), "Enable verbose output")
+)
+
+func addJsonOutputFlag(cmd *cobra.Command) {
+	cmd.PersistentFlags().BoolVarP(&jsonOutputFlag.Value, jsonOutputFlag.Name(), "", jsonOutputFlagDefault, jsonOutputFlag.Usage())
+}
+
+func addNoColorFlag(cmd *cobra.Command) {
+	cmd.PersistentFlags().BoolVarP(&noColorFlag.Value, noColorFlag.Name(), "", noColorFlagDefault, noColorFlag.Usage())
+}
+
+func addQuietFlag(cmd *cobra.Command) {
+	cmd.PersistentFlags().BoolVarP(&quietFlag.Value, quietFlag.Name(), quietFlagShortCode, quietFlagDefault, quietFlag.Usage())
+}
+
+func addVerboseFlag(cmd *cobra.Command) {
+	cmd.PersistentFlags().BoolVarP(&verboseFlag.Value, verboseFlag.Name(), verboseFlagShortCode, verboseFlagDefault, verboseFlag.Usage())
+}
+
+func configureOutputFlags(cmd *cobra.Command) {
+	addJsonOutputFlag(cmd)
+	addNoColorFlag(cmd)
+	addVerboseFlag(cmd)
+	addQuietFlag(cmd)
+
+	cmd.MarkFlagsMutuallyExclusive(verboseFlag.Name(), quietFlag.Name(), jsonOutputFlag.Name())
+	cmd.MarkFlagsMutuallyExclusive(jsonOutputFlag.Name(), noColorFlag.Name())
+	cmd.MarkFlagsMutuallyExclusive(quietFlag.Name(), noColorFlag.Name())
+}

application/version.go

@@ -0,0 +1,96 @@
+package application
+
+import (
+	"encoding/json"
+	"fmt"
+	"regexp"
+
+	"github.com/Oudwins/zog"
+	"github.com/spf13/cobra"
+
+	"git.flexabyte.io/flexabyte/go-kit/flagzog"
+)
+
+const (
+	versionFlagName      = "version"
+	versionFlagShortCode = "V"
+	versionFlagUsage     = "Show version information"
+	versionFlagDefault   = false
+
+	// https://semver.org/ && https://regex101.com/r/Ly7O1x/3/
+	validSemVer = `^(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<prerelease>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P<buildmetadata>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$`
+)
+
+var (
+	versionFlag = flagzog.NewBoolFlag(versionFlagName, zog.Bool(), versionFlagUsage)
+	version     Version
+	versionCmd  = &cobra.Command{
+		Use:   versionFlagName,
+		Short: versionFlagUsage,
+		RunE:  versionRunFuncE,
+	}
+
+	regexSemver = regexp.MustCompile(validSemVer)
+)
+
+type Version struct {
+	Full       string
+	Branch     string
+	Tag        string
+	Commit     string
+	CommitDate string
+	BuildDate  string
+	Major      string
+	Minor      string
+	Patch      string
+	PreRelease string
+}
+
+func (v Version) IsValid() bool {
+	return regexSemver.MatchString(v.Full)
+}
+
+func addVersionFlag(cmd *cobra.Command) {
+	cmd.PersistentFlags().BoolVarP(&versionFlag.Value, versionFlag.Name(), versionFlagShortCode, versionFlagDefault, versionFlag.Usage())
+}
+
+func configureVersionFlag(cmd *cobra.Command, v Version) {
+	version = v
+	cmd.AddCommand(versionCmd)
+	addVersionFlag(cmd)
+}
+
+func printVersion(v Version) string {
+	var output string
+	if !verboseFlag.Value {
+		output = v.Full
+	}
+
+	if jsonOutputFlag.Value {
+		var b []byte
+		b, _ = json.Marshal(v)
+		output = string(b)
+	}
+
+	if output != "" {
+		return output
+	}
+	return fmt.Sprintf(
+		"Full: %s\nBranch: %s\nTag: %s\nCommit: %s\nCommit date: %s\nBuild date: %s\nMajor: %s\nMinor: %s\nPatch: %s\nPreRelease: %s\n",
+		v.Full,
+		v.Branch,
+		v.Tag,
+		v.Commit,
+		v.CommitDate,
+		v.BuildDate,
+		v.Major,
+		v.Minor,
+		v.Patch,
+		v.PreRelease,
+	)
+}
+
+func versionRunFuncE(cmd *cobra.Command, args []string) error {
+	_, err := fmt.Fprintln(outWriter, printVersion(version))
+	return err
+}

examples/application/simple/go.mod

@@ -0,0 +1,19 @@
+module simple
+
+go 1.24.2
+
+toolchain go1.24.4
+
+require (
+	git.flexabyte.io/flexabyte/go-kit v0.1.1-0.20250609193926-e63b41c5ff45
+	github.com/spf13/cobra v1.9.1
+)
+
+require (
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/samber/lo v1.50.0 // indirect
+	github.com/samber/slog-formatter v1.2.0 // indirect
+	github.com/samber/slog-multi v1.4.0 // indirect
+	github.com/spf13/pflag v1.0.6 // indirect
+	golang.org/x/text v0.26.0 // indirect
+)

examples/application/simple/go.sum

@@ -0,0 +1,27 @@
+git.flexabyte.io/flexabyte/go-kit v0.1.1-0.20250609193926-e63b41c5ff45 h1:VA4K969jlxvppt+WYHIMwTt5TnE9zgEynMu1reTFujQ=
+git.flexabyte.io/flexabyte/go-kit v0.1.1-0.20250609193926-e63b41c5ff45/go.mod h1:GTo5se9ocEJfsdlpClpZMD8+eXsHdD5it35IILezNUc=
+github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
+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/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
+github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+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/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/samber/lo v1.50.0 h1:XrG0xOeHs+4FQ8gJR97zDz5uOFMW7OwFWiFVzqopKgY=
+github.com/samber/lo v1.50.0/go.mod h1:RjZyNk6WSnUFRKK6EyOhsRJMqft3G+pg7dCWHQCWvsc=
+github.com/samber/slog-formatter v1.2.0 h1:gTSHm4CxyySyhcxRkzk21CSKbGCdZVipbRMhINkNtQU=
+github.com/samber/slog-formatter v1.2.0/go.mod h1:hgjhSd5Vf69XCOnVp0UW0QHCxJ8iDEm/qASjji6FNoI=
+github.com/samber/slog-multi v1.4.0 h1:pwlPMIE7PrbTHQyKWDU+RIoxP1+HKTNOujk3/kdkbdg=
+github.com/samber/slog-multi v1.4.0/go.mod h1:FsQ4Uv2L+E/8TZt+/BVgYZ1LoDWCbfCU21wVIoMMrO8=
+github.com/spf13/cobra v1.9.1 h1:CXSaggrXdbHK9CF+8ywj8Amf7PBRmPCOJugH954Nnlo=
+github.com/spf13/cobra v1.9.1/go.mod h1:nDyEzZ8ogv936Cinf6g1RU9MRY64Ir93oCnqb9wxYW0=
+github.com/spf13/pflag v1.0.6 h1:jFzHGLGAlb3ruxLB8MhbI6A8+AQX/2eW4qeyNZXNp2o=
+github.com/spf13/pflag v1.0.6/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+golang.org/x/text v0.26.0 h1:P42AVeLghgTYr4+xUnTRKDMqpar+PtX7KWuNQL21L8M=
+golang.org/x/text v0.26.0/go.mod h1:QK15LZJUUQVJxhz7wXgxSy/CJaTFjd0G+YLonydOVQA=
+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=

examples/application/simple/main.go

@@ -0,0 +1,79 @@
+package main
+
+import (
+	"context"
+	"log/slog"
+	"net/http"
+	"os"
+	"time"
+
+	"github.com/spf13/cobra"
+
+	"git.flexabyte.io/flexabyte/go-kit/application"
+	"git.flexabyte.io/flexabyte/go-kit/httpd"
+	"git.flexabyte.io/flexabyte/go-kit/slogd"
+)
+
+var (
+	version    string = "0.1.0-alpha.0+metadata.20101112"
+	branch     string = "0.1.0-dev"
+	tag        string = "0.1.0-dev.0"
+	commit     string = "aabbccddee"
+	commitDate string = time.Now().String()
+	buildDate  string = time.Now().String()
+
+	major      string = "0"
+	minor      string = "1"
+	patch      string = "0"
+	prerelease string = "dev"
+)
+
+func main() {
+	var err error
+	slogd.Init(application.GetLogLevelFromArgs(os.Args), false)
+	slogd.RegisterSink(slogd.HandlerText, slog.NewTextHandler(os.Stdout, slogd.HandlerOptions()), true)
+	ctx := slogd.WithContext(context.Background())
+
+	config := application.Config{
+		Name:   "main",
+		Title:  "Main Test",
+		Banner: "",
+		// Version:                "0.1.0-alpha.0+metadata.20101112",
+		Version: application.Version{
+			Full:       version,
+			Branch:     branch,
+			Tag:        tag,
+			Commit:     commit,
+			CommitDate: commitDate,
+			BuildDate:  buildDate,
+			Major:      major,
+			Minor:      minor,
+			Patch:      patch,
+			PreRelease: prerelease,
+		},
+		EnableGracefulShutdown: true,
+		Logger:                 slogd.Logger(),
+		OverrideRunE: func(cmd *cobra.Command, args []string) error {
+			mux := http.NewServeMux()
+			mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+				slogd.FromContext(r.Context()).LogAttrs(r.Context(), slogd.LevelInfo, "request received", slog.String("method", r.Method), slog.String("url", r.URL.String()), slog.String("user-agent", r.UserAgent()))
+			})
+			return httpd.RunHttpServer(cmd.Context(), slogd.Logger(), "127.0.0.1", 28000, mux, 5*time.Second)
+		},
+		PersistentPreRunE:        nil,
+		PersistentPostRunE:       nil,
+		ShutdownSignals:          application.DefaultShutdownSignals,
+		ShutdownTimeout:          5 * time.Second,
+		SubCommands:              nil,
+		SubCommandInitializeFunc: nil,
+		ValidArgs:                nil,
+	}
+	var app application.Application
+	if app, err = application.New(config); err != nil {
+		panic(err)
+	}
+
+	if err = app.ExecuteContext(ctx); err != nil {
+		panic(err)
+	}
+}

examples/sqr/embeddedSqlWithRepository/assets/migrations/01_demo.up.sql

@@ -0,0 +1,13 @@
+CREATE TABLE IF NOT EXISTS demo
+(
+    id   INTEGER NOT NULL
+        CONSTRAINT p_id
+            PRIMARY KEY AUTOINCREMENT,
+    name TEXT    NOT NULL
+        CONSTRAINT u_name
+            UNIQUE
+                ON CONFLICT FAIL
+);
+
+INSERT INTO demo (name)
+VALUES ('item1')

examples/sqr/embeddedSqlWithRepository/assets/statements/demo/deleteById.sql

@@ -0,0 +1,3 @@
+DELETE
+FROM demo
+WHERE id == ?

examples/sqr/embeddedSqlWithRepository/assets/statements/demo/deleteByName.sql

@@ -0,0 +1,3 @@
+DELETE
+FROM demo
+WHERE name == ?

examples/sqr/embeddedSqlWithRepository/assets/statements/demo/insert.sql

@@ -0,0 +1,3 @@
+INSERT INTO demo (name)
+VALUES (?)
+RETURNING id

examples/sqr/embeddedSqlWithRepository/assets/statements/demo/list.sql

@@ -0,0 +1,2 @@
+SELECT *
+FROM demo

examples/sqr/embeddedSqlWithRepository/assets/statements/test/list.sql

@@ -0,0 +1,2 @@
+SELECT *
+FROM test

examples/sqr/embeddedSqlWithRepository/go.mod

@@ -0,0 +1,27 @@
+module embeddedSql
+
+go 1.24.2
+
+toolchain go1.24.3
+
+require (
+	git.flexabyte.io/flexabyte/go-kit v0.1.0
+	github.com/golang-migrate/migrate/v4 v4.18.3
+)
+
+require (
+	github.com/dustin/go-humanize v1.0.1 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/hashicorp/errwrap v1.1.0 // indirect
+	github.com/hashicorp/go-multierror v1.1.1 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/ncruces/go-strftime v0.1.9 // indirect
+	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
+	go.uber.org/atomic v1.11.0 // indirect
+	golang.org/x/exp v0.0.0-20250606033433-dcc06ee1d476 // indirect
+	golang.org/x/sys v0.33.0 // indirect
+	modernc.org/libc v1.65.10 // indirect
+	modernc.org/mathutil v1.7.1 // indirect
+	modernc.org/memory v1.11.0 // indirect
+	modernc.org/sqlite v1.38.0 // indirect
+)

examples/sqr/embeddedSqlWithRepository/go.sum

@@ -0,0 +1,68 @@
+git.flexabyte.io/flexabyte/go-kit v0.1.0 h1:ATnnYfF9wl3mIxhGy1ki5k0lKqLftoCb+MjBGxUGbpA=
+git.flexabyte.io/flexabyte/go-kit v0.1.0/go.mod h1:+ZXfaSKiX1m0zrIy9YIHAK+MpEOgHfheuPS/rM6AMlM=
+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/golang-migrate/migrate/v4 v4.18.3 h1:EYGkoOsvgHHfm5U/naS1RP/6PL/Xv3S4B/swMiAmDLs=
+github.com/golang-migrate/migrate/v4 v4.18.3/go.mod h1:99BKpIi6ruaaXRM1A77eqZ+FWPQ3cfRa+ZVy5bmWMaY=
+github.com/google/pprof v0.0.0-20250317173921-a4b03ec1a45e h1:ijClszYn+mADRFY17kjQEVQ1XRhq2/JR1M3sGqeJoxs=
+github.com/google/pprof v0.0.0-20250317173921-a4b03ec1a45e/go.mod h1:boTsfXsheKC2y+lKOCMpSfarhxDeIzfZG1jqGcPl3cA=
+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/hashicorp/errwrap v1.0.0/go.mod h1:YH+1FKiLXxHSkmPseP+kNlulaMuP3n2brvKWEqk/Jc4=
+github.com/hashicorp/errwrap v1.1.0 h1:OxrOeh75EUXMY8TBjag2fzXGZ40LB6IKw45YeGUDY2I=
+github.com/hashicorp/errwrap v1.1.0/go.mod h1:YH+1FKiLXxHSkmPseP+kNlulaMuP3n2brvKWEqk/Jc4=
+github.com/hashicorp/go-multierror v1.1.1 h1:H5DkEtf6CXdFp0N0Em5UCwQpXMWke8IA0+lD48awMYo=
+github.com/hashicorp/go-multierror v1.1.1/go.mod h1:iw975J/qwKPdAO1clOe2L8331t/9/fmwbPZ6JB6eMoM=
+github.com/lib/pq v1.10.9 h1:YXG7RB+JIjhP29X+OtkiDnYaXQwpS4JEWq7dtCCRUEw=
+github.com/lib/pq v1.10.9/go.mod h1:AlVN5x4E4T544tWzH6hKfbfQvm3HdbOxrmggDNAPY9o=
+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/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/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
+github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
+github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+go.uber.org/atomic v1.11.0 h1:ZvwS0R+56ePWxUNi+Atn9dWONBPp/AUETXlHW0DxSjE=
+go.uber.org/atomic v1.11.0/go.mod h1:LUxbIzbOniOlMKjJjyPfpl4v+PKK2cNJn91OQbhoJI0=
+golang.org/x/exp v0.0.0-20250606033433-dcc06ee1d476 h1:bsqhLWFR6G6xiQcb+JoGqdKdRU6WzPWmK8E0jxTjzo4=
+golang.org/x/exp v0.0.0-20250606033433-dcc06ee1d476/go.mod h1:3//PLf8L/X+8b4vuAfHzxeRUl04Adcb341+IGKfnqS8=
+golang.org/x/mod v0.25.0 h1:n7a+ZbQKQA/Ysbyb0/6IbB1H/X41mKgbhfv7AfG/44w=
+golang.org/x/mod v0.25.0/go.mod h1:IXM97Txy2VM4PJ3gI61r1YEk/gAj6zAHN3AdZt6S9Ww=
+golang.org/x/sync v0.15.0 h1:KWH3jNZsfyT6xfAfKiz6MRNmd46ByHDYaZ7KSkCtdW8=
+golang.org/x/sync v0.15.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA=
+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=
+golang.org/x/tools v0.34.0 h1:qIpSLOxeCYGg9TrcJokLBG4KFA6d795g0xkBkiESGlo=
+golang.org/x/tools v0.34.0/go.mod h1:pAP9OwEaY1CAW3HOmg3hLZC5Z0CCmzjAF2UQMSqNARg=
+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/cc/v4 v4.26.1 h1:+X5NtzVBn0KgsBCBe+xkDC7twLb/jNVj9FPgiwSQO3s=
+modernc.org/cc/v4 v4.26.1/go.mod h1:uVtb5OGqUKpoLWhqwNQo/8LwvoiEBLvZXIQ/SmO6mL0=
+modernc.org/ccgo/v4 v4.28.0 h1:rjznn6WWehKq7dG4JtLRKxb52Ecv8OUGah8+Z/SfpNU=
+modernc.org/ccgo/v4 v4.28.0/go.mod h1:JygV3+9AV6SmPhDasu4JgquwU81XAKLd3OKTUDNOiKE=
+modernc.org/fileutil v1.3.3 h1:3qaU+7f7xxTUmvU1pJTZiDLAIoJVdUSSauJNHg9yXoA=
+modernc.org/fileutil v1.3.3/go.mod h1:HxmghZSZVAz/LXcMNwZPA/DRrQZEVP9VX0V4LQGQFOc=
+modernc.org/gc/v2 v2.6.5 h1:nyqdV8q46KvTpZlsw66kWqwXRHdjIlJOhG6kxiV/9xI=
+modernc.org/gc/v2 v2.6.5/go.mod h1:YgIahr1ypgfe7chRuJi2gD7DBQiKSLMPgBQe9oIiito=
+modernc.org/libc v1.65.10 h1:ZwEk8+jhW7qBjHIT+wd0d9VjitRyQef9BnzlzGwMODc=
+modernc.org/libc v1.65.10/go.mod h1:StFvYpx7i/mXtBAfVOjaU0PWZOvIRoZSgXhrwXzr8Po=
+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.11.0 h1:o4QC8aMQzmcwCK3t3Ux/ZHmwFPzE6hf2Y5LbkRs+hbI=
+modernc.org/memory v1.11.0/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw=
+modernc.org/opt v0.1.4 h1:2kNGMRiUjrp4LcaPuLY2PzUfqM/w9N23quVwhKt5Qm8=
+modernc.org/opt v0.1.4/go.mod h1:03fq9lsNfvkYSfxrfUhZCWPk1lm4cq4N+Bh//bEtgns=
+modernc.org/sortutil v1.2.1 h1:+xyoGf15mM3NMlPDnFqrteY07klSFxLElE2PVuWIJ7w=
+modernc.org/sortutil v1.2.1/go.mod h1:7ZI3a3REbai7gzCLcotuw9AC4VZVpYMjDzETGsSMqJE=
+modernc.org/sqlite v1.38.0 h1:+4OrfPQ8pxHKuWG4md1JpR/EYAh3Md7TdejuuzE7EUI=
+modernc.org/sqlite v1.38.0/go.mod h1:1Bj+yES4SVvBZ4cBOpVZ6QgesMCKpJZDq0nxYzOpmNE=
+modernc.org/strutil v1.2.1 h1:UneZBkQA+DX2Rp35KcM69cSsNES9ly8mQWD71HKlOA0=
+modernc.org/strutil v1.2.1/go.mod h1:EHkiggD70koQxjVdSBM3JKM7k6L0FbGE5eymy9i3B9A=
+modernc.org/token v1.1.0 h1:Xl7Ap9dKaEs5kLoOQeQmPWevfnk/DM5qcLcYlA8ys6Y=
+modernc.org/token v1.1.0/go.mod h1:UGzOrNV1mAFSEB63lOFHIpNRUVMvYTc6yu1SMY/XTDM=

examples/sqr/embeddedSqlWithRepository/main.go

@@ -0,0 +1,124 @@
+package main
+
+import (
+	"database/sql"
+	"embed"
+	"errors"
+	"fmt"
+
+	"git.flexabyte.io/flexabyte/go-kit/sqr"
+	"github.com/golang-migrate/migrate/v4"
+	"github.com/golang-migrate/migrate/v4/database"
+	"github.com/golang-migrate/migrate/v4/database/sqlite"
+	"github.com/golang-migrate/migrate/v4/source"
+	"github.com/golang-migrate/migrate/v4/source/iofs"
+)
+
+//go:embed assets/migrations/*
+var migrationFs embed.FS
+
+//go:embed assets/statements/*
+var statementsFS embed.FS
+
+var db *sql.DB
+
+var r *sqr.Repository
+
+func main() {
+	var err error
+
+	fmt.Println("Create in-memory database and run migrations:")
+	// Create in-memory demo database
+	if err = initialize(); err != nil {
+		panic(err)
+	}
+
+	// Create query repository from embedded files
+	if r, err = sqr.NewFromFs(statementsFS, "assets/statements"); err != nil {
+		panic(err)
+	}
+	fmt.Println("")
+
+	fmt.Println("Fetch statements from repository:")
+	var query string
+	if query, err = r.Get("demo", "list"); err != nil {
+		panic(err)
+	}
+	fmt.Println("Query:", query)
+
+	if query, err = r.Get("demo", "insert"); err != nil {
+		panic(err)
+	}
+	fmt.Println("Query:", query)
+	fmt.Println("")
+
+	fmt.Println("Run insert statement:")
+	var stmtInsert *sql.Stmt
+	if stmtInsert, err = sqr.Prepare(db, r, "demo", "insert"); err != nil {
+		panic(err)
+	}
+
+	var res int
+	if err = stmtInsert.QueryRow("item2").Scan(&res); err != nil {
+		panic(err)
+	}
+	fmt.Println("Successfully inserted into database, returned id:", res)
+
+	fmt.Println("")
+	fmt.Println("Run list statement:")
+	var stmtQuery *sql.Stmt
+	if stmtQuery, err = sqr.Prepare(db, r, "demo", "list"); err != nil {
+		fmt.Println("Error preparing statement")
+	}
+
+	if stmtQuery == nil {
+		panic(errors.New("statement not found"))
+	}
+
+	var rows *sql.Rows
+	if rows, err = stmtQuery.Query(); err != nil {
+		fmt.Println("Error querying statement")
+	}
+	if rows != nil {
+		for rows.Next() {
+			var id int
+			var name string
+			if err = rows.Scan(&id, &name); err != nil {
+				fmt.Println("Error scanning row")
+			}
+			fmt.Println("Output", id, name)
+		}
+	}
+
+}
+
+func initialize() error {
+	var err error
+	db, err = sql.Open("sqlite", ":memory:")
+	if err != nil {
+		fmt.Println("Error opening database")
+		return err
+	}
+
+	var src source.Driver
+	if src, err = iofs.New(migrationFs, "assets/migrations"); err != nil {
+		fmt.Println("Error opening migrations source")
+		return err
+	}
+
+	var driver database.Driver
+	if driver, err = sqlite.WithInstance(db, &sqlite.Config{}); err != nil {
+		fmt.Println("Error opening migrations destination")
+		return err
+	}
+
+	var m *migrate.Migrate
+	if m, err = migrate.NewWithInstance("fs", src, "sqlite", driver); err != nil {
+		return err
+	}
+
+	if err = m.Up(); err != nil && !errors.Is(err, migrate.ErrNoChange) {
+		return err
+	}
+	return nil
+}

examples/sqr/embeddedSqlWithoutRepository/assets/migrations/01_demo.up.sql

@@ -0,0 +1,13 @@
+CREATE TABLE IF NOT EXISTS demo
+(
+    id   INTEGER NOT NULL
+        CONSTRAINT p_id
+            PRIMARY KEY AUTOINCREMENT,
+    name TEXT    NOT NULL
+        CONSTRAINT u_name
+            UNIQUE
+                ON CONFLICT FAIL
+);
+
+INSERT INTO demo (name)
+VALUES ('item1')

examples/sqr/embeddedSqlWithoutRepository/assets/statements/demo/deleteById.sql

@@ -0,0 +1,3 @@
+DELETE
+FROM demo
+WHERE id == ?

examples/sqr/embeddedSqlWithoutRepository/assets/statements/demo/deleteByName.sql

@@ -0,0 +1,3 @@
+DELETE
+FROM demo
+WHERE name == ?

examples/sqr/embeddedSqlWithoutRepository/assets/statements/demo/insert.sql

@@ -0,0 +1,3 @@
+INSERT INTO demo (name)
+VALUES (?)
+RETURNING id

examples/sqr/embeddedSqlWithoutRepository/assets/statements/demo/list.sql

@@ -0,0 +1,2 @@
+SELECT *
+FROM demo

examples/sqr/embeddedSqlWithoutRepository/assets/statements/test/list.sql

@@ -0,0 +1,2 @@
+SELECT *
+FROM test

examples/sqr/embeddedSqlWithoutRepository/go.mod

@@ -0,0 +1,27 @@
+module embeddedSql
+
+go 1.24.2
+
+toolchain go1.24.3
+
+require (
+	git.flexabyte.io/flexabyte/go-kit v0.1.0
+	github.com/golang-migrate/migrate/v4 v4.18.3
+)
+
+require (
+	github.com/dustin/go-humanize v1.0.1 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/hashicorp/errwrap v1.1.0 // indirect
+	github.com/hashicorp/go-multierror v1.1.1 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/ncruces/go-strftime v0.1.9 // indirect
+	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
+	go.uber.org/atomic v1.11.0 // indirect
+	golang.org/x/exp v0.0.0-20250606033433-dcc06ee1d476 // indirect
+	golang.org/x/sys v0.33.0 // indirect
+	modernc.org/libc v1.65.10 // indirect
+	modernc.org/mathutil v1.7.1 // indirect
+	modernc.org/memory v1.11.0 // indirect
+	modernc.org/sqlite v1.38.0 // indirect
+)

examples/sqr/embeddedSqlWithoutRepository/go.sum

@@ -0,0 +1,68 @@
+git.flexabyte.io/flexabyte/go-kit v0.1.0 h1:ATnnYfF9wl3mIxhGy1ki5k0lKqLftoCb+MjBGxUGbpA=
+git.flexabyte.io/flexabyte/go-kit v0.1.0/go.mod h1:+ZXfaSKiX1m0zrIy9YIHAK+MpEOgHfheuPS/rM6AMlM=
+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/golang-migrate/migrate/v4 v4.18.3 h1:EYGkoOsvgHHfm5U/naS1RP/6PL/Xv3S4B/swMiAmDLs=
+github.com/golang-migrate/migrate/v4 v4.18.3/go.mod h1:99BKpIi6ruaaXRM1A77eqZ+FWPQ3cfRa+ZVy5bmWMaY=
+github.com/google/pprof v0.0.0-20250317173921-a4b03ec1a45e h1:ijClszYn+mADRFY17kjQEVQ1XRhq2/JR1M3sGqeJoxs=
+github.com/google/pprof v0.0.0-20250317173921-a4b03ec1a45e/go.mod h1:boTsfXsheKC2y+lKOCMpSfarhxDeIzfZG1jqGcPl3cA=
+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/hashicorp/errwrap v1.0.0/go.mod h1:YH+1FKiLXxHSkmPseP+kNlulaMuP3n2brvKWEqk/Jc4=
+github.com/hashicorp/errwrap v1.1.0 h1:OxrOeh75EUXMY8TBjag2fzXGZ40LB6IKw45YeGUDY2I=
+github.com/hashicorp/errwrap v1.1.0/go.mod h1:YH+1FKiLXxHSkmPseP+kNlulaMuP3n2brvKWEqk/Jc4=
+github.com/hashicorp/go-multierror v1.1.1 h1:H5DkEtf6CXdFp0N0Em5UCwQpXMWke8IA0+lD48awMYo=
+github.com/hashicorp/go-multierror v1.1.1/go.mod h1:iw975J/qwKPdAO1clOe2L8331t/9/fmwbPZ6JB6eMoM=
+github.com/lib/pq v1.10.9 h1:YXG7RB+JIjhP29X+OtkiDnYaXQwpS4JEWq7dtCCRUEw=
+github.com/lib/pq v1.10.9/go.mod h1:AlVN5x4E4T544tWzH6hKfbfQvm3HdbOxrmggDNAPY9o=
+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/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/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
+github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
+github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+go.uber.org/atomic v1.11.0 h1:ZvwS0R+56ePWxUNi+Atn9dWONBPp/AUETXlHW0DxSjE=
+go.uber.org/atomic v1.11.0/go.mod h1:LUxbIzbOniOlMKjJjyPfpl4v+PKK2cNJn91OQbhoJI0=
+golang.org/x/exp v0.0.0-20250606033433-dcc06ee1d476 h1:bsqhLWFR6G6xiQcb+JoGqdKdRU6WzPWmK8E0jxTjzo4=
+golang.org/x/exp v0.0.0-20250606033433-dcc06ee1d476/go.mod h1:3//PLf8L/X+8b4vuAfHzxeRUl04Adcb341+IGKfnqS8=
+golang.org/x/mod v0.25.0 h1:n7a+ZbQKQA/Ysbyb0/6IbB1H/X41mKgbhfv7AfG/44w=
+golang.org/x/mod v0.25.0/go.mod h1:IXM97Txy2VM4PJ3gI61r1YEk/gAj6zAHN3AdZt6S9Ww=
+golang.org/x/sync v0.15.0 h1:KWH3jNZsfyT6xfAfKiz6MRNmd46ByHDYaZ7KSkCtdW8=
+golang.org/x/sync v0.15.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA=
+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=
+golang.org/x/tools v0.34.0 h1:qIpSLOxeCYGg9TrcJokLBG4KFA6d795g0xkBkiESGlo=
+golang.org/x/tools v0.34.0/go.mod h1:pAP9OwEaY1CAW3HOmg3hLZC5Z0CCmzjAF2UQMSqNARg=
+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/cc/v4 v4.26.1 h1:+X5NtzVBn0KgsBCBe+xkDC7twLb/jNVj9FPgiwSQO3s=
+modernc.org/cc/v4 v4.26.1/go.mod h1:uVtb5OGqUKpoLWhqwNQo/8LwvoiEBLvZXIQ/SmO6mL0=
+modernc.org/ccgo/v4 v4.28.0 h1:rjznn6WWehKq7dG4JtLRKxb52Ecv8OUGah8+Z/SfpNU=
+modernc.org/ccgo/v4 v4.28.0/go.mod h1:JygV3+9AV6SmPhDasu4JgquwU81XAKLd3OKTUDNOiKE=
+modernc.org/fileutil v1.3.3 h1:3qaU+7f7xxTUmvU1pJTZiDLAIoJVdUSSauJNHg9yXoA=
+modernc.org/fileutil v1.3.3/go.mod h1:HxmghZSZVAz/LXcMNwZPA/DRrQZEVP9VX0V4LQGQFOc=
+modernc.org/gc/v2 v2.6.5 h1:nyqdV8q46KvTpZlsw66kWqwXRHdjIlJOhG6kxiV/9xI=
+modernc.org/gc/v2 v2.6.5/go.mod h1:YgIahr1ypgfe7chRuJi2gD7DBQiKSLMPgBQe9oIiito=
+modernc.org/libc v1.65.10 h1:ZwEk8+jhW7qBjHIT+wd0d9VjitRyQef9BnzlzGwMODc=
+modernc.org/libc v1.65.10/go.mod h1:StFvYpx7i/mXtBAfVOjaU0PWZOvIRoZSgXhrwXzr8Po=
+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.11.0 h1:o4QC8aMQzmcwCK3t3Ux/ZHmwFPzE6hf2Y5LbkRs+hbI=
+modernc.org/memory v1.11.0/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw=
+modernc.org/opt v0.1.4 h1:2kNGMRiUjrp4LcaPuLY2PzUfqM/w9N23quVwhKt5Qm8=
+modernc.org/opt v0.1.4/go.mod h1:03fq9lsNfvkYSfxrfUhZCWPk1lm4cq4N+Bh//bEtgns=
+modernc.org/sortutil v1.2.1 h1:+xyoGf15mM3NMlPDnFqrteY07klSFxLElE2PVuWIJ7w=
+modernc.org/sortutil v1.2.1/go.mod h1:7ZI3a3REbai7gzCLcotuw9AC4VZVpYMjDzETGsSMqJE=
+modernc.org/sqlite v1.38.0 h1:+4OrfPQ8pxHKuWG4md1JpR/EYAh3Md7TdejuuzE7EUI=
+modernc.org/sqlite v1.38.0/go.mod h1:1Bj+yES4SVvBZ4cBOpVZ6QgesMCKpJZDq0nxYzOpmNE=
+modernc.org/strutil v1.2.1 h1:UneZBkQA+DX2Rp35KcM69cSsNES9ly8mQWD71HKlOA0=
+modernc.org/strutil v1.2.1/go.mod h1:EHkiggD70koQxjVdSBM3JKM7k6L0FbGE5eymy9i3B9A=
+modernc.org/token v1.1.0 h1:Xl7Ap9dKaEs5kLoOQeQmPWevfnk/DM5qcLcYlA8ys6Y=
+modernc.org/token v1.1.0/go.mod h1:UGzOrNV1mAFSEB63lOFHIpNRUVMvYTc6yu1SMY/XTDM=

examples/sqr/embeddedSqlWithoutRepository/main.go

@@ -0,0 +1,116 @@
+package main
+
+import (
+	"database/sql"
+	"embed"
+	"errors"
+	"fmt"
+
+	"git.flexabyte.io/flexabyte/go-kit/sqr"
+	"github.com/golang-migrate/migrate/v4"
+	"github.com/golang-migrate/migrate/v4/database"
+	"github.com/golang-migrate/migrate/v4/database/sqlite"
+	"github.com/golang-migrate/migrate/v4/source"
+	"github.com/golang-migrate/migrate/v4/source/iofs"
+)
+
+//go:embed assets/migrations/*
+var migrationFs embed.FS
+
+//go:embed assets/statements/*
+var statementsFS embed.FS
+
+var db *sql.DB
+
+func main() {
+	var err error
+
+	fmt.Println("Create in-memory database and run migrations:")
+	// Create in-memory demo database
+	if err = initialize(); err != nil {
+		panic(err)
+	}
+
+	fmt.Println("Fetch demo list query from filesystem:")
+	var query string
+	if query, err = sqr.LoadQueryFromFs(statementsFS, "assets/statements", "demo", "list"); err != nil {
+		panic(err)
+	}
+	fmt.Println("Query:", query)
+
+	if query, err = sqr.LoadQueryFromFs(statementsFS, "assets/statements", "demo", "insert"); err != nil {
+		panic(err)
+	}
+	fmt.Println("Query:", query)
+	fmt.Println("")
+
+	fmt.Println("Run insert statement:")
+	var stmtInsert *sql.Stmt
+	if stmtInsert, err = sqr.PrepareFromFs(db, statementsFS, "assets/statements", "demo", "insert"); err != nil {
+		panic(err)
+	}
+
+	var res int
+	if err = stmtInsert.QueryRow("item2").Scan(&res); err != nil {
+		panic(err)
+	}
+	fmt.Println("Successfully inserted into database, returned id:", res)
+
+	fmt.Println("")
+	fmt.Println("Run list statement:")
+	var stmtQuery *sql.Stmt
+	if stmtQuery, err = sqr.PrepareFromFs(db, statementsFS, "assets/statements", "demo", "list"); err != nil {
+		fmt.Println("Error preparing statement")
+	}
+
+	if stmtQuery == nil {
+		panic(errors.New("statement not found"))
+	}
+
+	var rows *sql.Rows
+	if rows, err = stmtQuery.Query(); err != nil {
+		fmt.Println("Error querying statement")
+	}
+	if rows != nil {
+		for rows.Next() {
+			var id int
+			var name string
+			if err = rows.Scan(&id, &name); err != nil {
+				fmt.Println("Error scanning row")
+			}
+			fmt.Println("Output", id, name)
+		}
+	}
+
+}
+
+func initialize() error {
+	var err error
+	db, err = sql.Open("sqlite", ":memory:")
+	if err != nil {
+		fmt.Println("Error opening database")
+		return err
+	}
+
+	var src source.Driver
+	if src, err = iofs.New(migrationFs, "assets/migrations"); err != nil {
+		fmt.Println("Error opening migrations source")
+		return err
+	}
+
+	var driver database.Driver
+	if driver, err = sqlite.WithInstance(db, &sqlite.Config{}); err != nil {
+		fmt.Println("Error opening migrations destination")
+		return err
+	}
+
+	var m *migrate.Migrate
+	if m, err = migrate.NewWithInstance("fs", src, "sqlite", driver); err != nil {
+		return err
+	}
+
+	if err = m.Up(); err != nil && !errors.Is(err, migrate.ErrNoChange) {
+		return err
+	}
+	return nil
+}

flagzog/flags.go

@@ -0,0 +1,122 @@
+package flagzog
+
+import (
+	"fmt"
+
+	"github.com/Oudwins/zog"
+	"github.com/spf13/pflag"
+)
+
+func NewBoolFlag(name string, schema *zog.BoolSchema[bool], usage string) BoolFlag {
+	return BoolFlag{
+		name:   name,
+		schema: schema,
+		usage:  usage,
+	}
+}
+
+type BoolFlag struct {
+	name   string
+	schema *zog.BoolSchema[bool]
+	usage  string
+	Value  bool
+}
+
+func (f BoolFlag) Name() string {
+	return f.name
+}
+
+func (f BoolFlag) Usage() string {
+	return f.usage
+}
+
+func (f BoolFlag) Validate() ([]string, error) {
+	var messages []string
+	if issues := f.schema.Validate(&f.Value); issues != nil {
+		for _, issue := range issues {
+			messages = append(messages, issue.Message)
+		}
+		return messages, fmt.Errorf("validation failed for flag '%s' with value '%s'", f.Name(), f.Value)
+	}
+	return messages, nil
+}
+
+func (f BoolFlag) AddToCommandFlags(flagset *pflag.FlagSet, shorthand string, value interface{}) {
+	flagset.BoolVarP(&f.Value, f.Name(), shorthand, value.(bool), f.usage)
+}
+
+func NewInt64Flag(name string, schema *zog.NumberSchema[int64], usage string) Int64Flag {
+	return Int64Flag{
+		name:   name,
+		schema: schema,
+		usage:  usage,
+	}
+}
+
+type Int64Flag struct {
+	name   string
+	schema *zog.NumberSchema[int64]
+	usage  string
+	Value  int64
+}
+
+func (f Int64Flag) Name() string {
+	return f.name
+}
+
+func (f Int64Flag) Usage() string {
+	return f.usage
+}
+
+func (f Int64Flag) Validate() ([]string, error) {
+	var messages []string
+	if issues := f.schema.Validate(&f.Value); issues != nil {
+		for _, issue := range issues {
+			messages = append(messages, issue.Message)
+		}
+		return messages, fmt.Errorf("validation failed for flag '%s' with value '%s'", f.Name(), f.Value)
+	}
+	return messages, nil
+}
+
+func (f Int64Flag) AddToCommandFlags(flagset *pflag.FlagSet, shorthand string, value interface{}) {
+	flagset.Int64VarP(&f.Value, f.Name(), shorthand, value.(int64), f.usage)
+}
+
+func NewStringFlag(name string, schema *zog.StringSchema[string], usage string) StringFlag {
+	return StringFlag{
+		name:   name,
+		schema: schema,
+		usage:  usage,
+	}
+}
+
+type StringFlag struct {
+	name   string
+	schema *zog.StringSchema[string]
+	usage  string
+	Value  string
+}
+
+func (f StringFlag) Name() string {
+	return f.name
+}
+
+func (f StringFlag) Usage() string {
+	return f.usage
+}
+
+func (f StringFlag) Validate() ([]string, error) {
+	var messages []string
+	if issues := f.schema.Validate(&f.Value); issues != nil {
+		for _, issue := range issues {
+			messages = append(messages, issue.Message)
+		}
+		return messages, fmt.Errorf("validation failed for flag '%s' with value '%s'", f.Name(), f.Value)
+	}
+	return messages, nil
+}
+
+func (f StringFlag) AddToCommandFlags(flagset *pflag.FlagSet, shorthand string, value interface{}) {
+	flagset.StringVarP(&f.Value, f.Name(), shorthand, value.(string), f.usage)
+}

flagzog/validator.go

@@ -0,0 +1,30 @@
+package flagzog
+
+import (
+	"context"
+	"log/slog"
+
+	"github.com/spf13/pflag"
+)
+
+type FlagValidator interface {
+	Name() string
+	Validate() ([]string, error)
+	Usage() string
+	AddToCommandFlags(flagset *pflag.FlagSet, shorthand string, value interface{})
+}
+
+func ValidateFlags(ctx context.Context, logger *slog.Logger, flags []FlagValidator) ([]string, error) {
+	var validatedFlags []string
+	var err error
+
+	for _, flag := range flags {
+		var issues []string
+		if issues, err = flag.Validate(); err != nil {
+			logger.Log(ctx, slog.LevelError, "validation failed", slog.String("flag", flag.Name()), slog.Any("issues", issues))
+			return validatedFlags, err
+		}
+		validatedFlags = append(validatedFlags, flag.Name())
+	}
+	return validatedFlags, nil
+}

go.mod

@@ -0,0 +1,18 @@
+module git.flexabyte.io/flexabyte/go-kit
+
+go 1.24.2
+
+require (
+	github.com/Oudwins/zog v0.21.1
+	github.com/samber/slog-formatter v1.2.0
+	github.com/samber/slog-multi v1.4.0
+	github.com/spf13/cobra v1.9.1
+	github.com/spf13/pflag v1.0.6
+)
+
+require (
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/samber/lo v1.50.0 // indirect
+	golang.org/x/exp v0.0.0-20250606033433-dcc06ee1d476 // indirect
+	golang.org/x/text v0.26.0 // indirect
+)

go.sum

@@ -0,0 +1,31 @@
+github.com/Oudwins/zog v0.21.1 h1:y6Ix9vNkDF8crLzOTU0A6kjT+uv5pgkHer9CBjYp93A=
+github.com/Oudwins/zog v0.21.1/go.mod h1:c4ADJ2zNkJp37ZViNy1o3ZZoeMvO7UQVO7BaPtRoocg=
+github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
+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/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
+github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+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/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/samber/lo v1.50.0 h1:XrG0xOeHs+4FQ8gJR97zDz5uOFMW7OwFWiFVzqopKgY=
+github.com/samber/lo v1.50.0/go.mod h1:RjZyNk6WSnUFRKK6EyOhsRJMqft3G+pg7dCWHQCWvsc=
+github.com/samber/slog-formatter v1.2.0 h1:gTSHm4CxyySyhcxRkzk21CSKbGCdZVipbRMhINkNtQU=
+github.com/samber/slog-formatter v1.2.0/go.mod h1:hgjhSd5Vf69XCOnVp0UW0QHCxJ8iDEm/qASjji6FNoI=
+github.com/samber/slog-multi v1.4.0 h1:pwlPMIE7PrbTHQyKWDU+RIoxP1+HKTNOujk3/kdkbdg=
+github.com/samber/slog-multi v1.4.0/go.mod h1:FsQ4Uv2L+E/8TZt+/BVgYZ1LoDWCbfCU21wVIoMMrO8=
+github.com/spf13/cobra v1.9.1 h1:CXSaggrXdbHK9CF+8ywj8Amf7PBRmPCOJugH954Nnlo=
+github.com/spf13/cobra v1.9.1/go.mod h1:nDyEzZ8ogv936Cinf6g1RU9MRY64Ir93oCnqb9wxYW0=
+github.com/spf13/pflag v1.0.6 h1:jFzHGLGAlb3ruxLB8MhbI6A8+AQX/2eW4qeyNZXNp2o=
+github.com/spf13/pflag v1.0.6/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+golang.org/x/exp v0.0.0-20240613232115-7f521ea00fb8 h1:yixxcjnhBmY0nkL253HFVIm0JsFHwrHdT3Yh6szTnfY=
+golang.org/x/exp v0.0.0-20240613232115-7f521ea00fb8/go.mod h1:jj3sYF3dwk5D+ghuXyeI3r5MFf+NT2An6/9dOA95KSI=
+golang.org/x/exp v0.0.0-20250606033433-dcc06ee1d476 h1:bsqhLWFR6G6xiQcb+JoGqdKdRU6WzPWmK8E0jxTjzo4=
+golang.org/x/exp v0.0.0-20250606033433-dcc06ee1d476/go.mod h1:3//PLf8L/X+8b4vuAfHzxeRUl04Adcb341+IGKfnqS8=
+golang.org/x/text v0.26.0 h1:P42AVeLghgTYr4+xUnTRKDMqpar+PtX7KWuNQL21L8M=
+golang.org/x/text v0.26.0/go.mod h1:QK15LZJUUQVJxhz7wXgxSy/CJaTFjd0G+YLonydOVQA=
+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=

httpd/httpd.go

@@ -0,0 +1,90 @@
+package httpd
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"net"
+	"net/http"
+	"strconv"
+	"time"
+
+	"git.flexabyte.io/flexabyte/go-kit/slogd"
+)
+
+func RunHttpServer(ctx context.Context, log *slog.Logger, listenAddress string, port int, h http.Handler, shutdownTimeout time.Duration) error {
+	s := &http.Server{
+		Addr:    listenAddress + ":" + strconv.Itoa(port),
+		Handler: h}
+
+	log.LogAttrs(ctx, slogd.LevelTrace, "starting http server", slog.String("listenAddress", fmt.Sprintf("http://%s", s.Addr)))
+
+	shutdownCtx, shutdownCancel := context.WithCancel(ctx)
+	defer shutdownCancel()
+
+	// Run goroutine to handle graceful shutdown
+	idleConnectionsClosed := make(chan struct{})
+	go shutdown(shutdownCtx, log, s, shutdownTimeout, idleConnectionsClosed)
+
+	var err error
+	if err = s.ListenAndServe(); !errors.Is(err, http.ErrServerClosed) {
+		// Error starting or closing listener:
+		log.LogAttrs(ctx, slogd.LevelError, "http server start failed", slog.String("error", err.Error()))
+		return err
+	}
+
+	<-idleConnectionsClosed
+	return err
+}
+
+func RunSocketHttpServer(ctx context.Context, log *slog.Logger, socketPath string, h http.Handler, shutdownTimeout time.Duration) error {
+	s := &http.Server{
+		Handler: h}
+
+	log.LogAttrs(ctx, slogd.LevelTrace, "starting http server", slog.String("socket", s.Addr))
+
+	shutdownCtx, shutdownCancel := context.WithCancel(ctx)
+	defer shutdownCancel()
+
+	// Run goroutine to handle graceful shutdown
+	idleConnectionsClosed := make(chan struct{})
+	go shutdown(shutdownCtx, log, s, shutdownTimeout, idleConnectionsClosed)
+
+	var err error
+	var config = new(net.ListenConfig)
+	var socket net.Listener
+
+	if socket, err = config.Listen(ctx, "unix", socketPath); err != nil {
+		log.LogAttrs(ctx, slogd.LevelError, "failed to listen on socket", slog.String("error", err.Error()))
+		return err
+	}
+
+	if err = s.Serve(socket); err != nil && !errors.Is(err, http.ErrServerClosed) {
+		// Error starting or closing listener:
+		log.LogAttrs(ctx, slogd.LevelError, "http server start failed", slog.String("error", err.Error()))
+		return err
+	}
+
+	<-idleConnectionsClosed
+	return err
+}
+
+func shutdown(ctx context.Context, log *slog.Logger, s *http.Server, shutdownTimeout time.Duration, idleConnectionsClosed chan struct{}) {
+	log.LogAttrs(ctx, slogd.LevelTrace, "awaiting shutdown signal for http server", slog.String("listenAddress", s.Addr))
+	<-ctx.Done()
+
+	// When shutdown signal is received, create a new context with the configured shutdown timeout
+	shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), shutdownTimeout)
+	defer shutdownCancel()
+
+	log.LogAttrs(shutdownCtx, slogd.LevelTrace, "shutdown signal received for http server", slog.String("listenAddress", s.Addr))
+	time.Sleep(2 * time.Second)
+	// We received an interrupt signal, shut down.
+	if err := s.Shutdown(shutdownCtx); err != nil {
+		// Error from closing listeners, or context timeout:
+		log.LogAttrs(ctx, slogd.LevelTrace, "shutdown for http server failed", slog.String("listenAddress", s.Addr), slog.Any("error", err))
+	}
+	log.LogAttrs(shutdownCtx, slogd.LevelTrace, "shutdown for http server completed", slog.String("listenAddress", s.Addr))
+	close(idleConnectionsClosed)
+}

semver/metadata.go

@@ -0,0 +1,23 @@
+package semver
+
+import (
+	"fmt"
+	"regexp"
+)
+
+const (
+	validMetadata = `^(?P<commit>[0-9a-zA-Z]{8}).(?P<date>[0-9]{8})$`
+)
+
+var regexMetadata = regexp.MustCompile(validMetadata)
+
+type Metadata string
+
+func SplitMetadata(m Metadata) (string, string, error) {
+	if !regexMetadata.MatchString(string(m)) {
+		return "", "", fmt.Errorf("invalid metadata: %s", m)
+	}
+
+	match := regexMetadata.FindStringSubmatch(string(m))
+	return match[1], match[2], nil
+}

semver/metadata_test.go

@@ -0,0 +1,37 @@
+package semver
+
+import "testing"
+
+var validMetadataTests = []struct {
+	name     string
+	metadata Metadata
+	commit   string
+	date     string
+	err      bool
+}{
+	{
+		name:     "simple",
+		metadata: "metadata.20101112",
+		commit:   "metadata",
+		date:     "20101112",
+		err:      false,
+	},
+}
+
+func TestSplitMetadata(t *testing.T) {
+	for _, tt := range validMetadataTests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, got1, err := SplitMetadata(tt.metadata)
+			if (err != nil) != tt.err {
+				t.Errorf("SplitMetadata() error = %v, wantErr %v", err, tt.err)
+				return
+			}
+			if got != tt.commit {
+				t.Errorf("SplitMetadata() got = %v, want %v", got, tt.commit)
+			}
+			if got1 != tt.date {
+				t.Errorf("SplitMetadata() got1 = %v, want %v", got1, tt.date)
+			}
+		})
+	}
+}

semver/prerelease.go

@@ -0,0 +1,3 @@
+package semver
+
+type PreRelease string

semver/version.go

@@ -0,0 +1,117 @@
+package semver
+
+import (
+	"bytes"
+	"fmt"
+	"regexp"
+	"strconv"
+)
+
+const (
+	// https://semver.org/ && https://regex101.com/r/Ly7O1x/3/
+	validSemVer = `^(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<prerelease>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P<buildmetadata>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$`
+)
+
+var regexSemver = regexp.MustCompile(validSemVer)
+
+type Version struct {
+	Major      int64
+	Minor      int64
+	Patch      int64
+	PreRelease PreRelease
+	Metadata   Metadata
+}
+
+func (v Version) Commit() string {
+	commit, _, err := SplitMetadata(v.Metadata)
+	if err != nil {
+		return string(v.Metadata)
+	}
+	return commit
+}
+
+func (v Version) Date() string {
+	_, date, err := SplitMetadata(v.Metadata)
+	if err != nil {
+		return string(v.Metadata)
+	}
+	return date
+}
+
+func (v Version) Release() string {
+	switch v.PreRelease {
+	case "":
+		return fmt.Sprint("stable")
+	default:
+		return string(v.PreRelease)
+	}
+}
+
+func (v Version) String() string {
+	var buf bytes.Buffer
+
+	fmt.Fprintf(&buf, "%d.%d.%d", v.Major, v.Minor, v.Patch)
+
+	if v.PreRelease != "" {
+		fmt.Fprintf(&buf, "-%s", v.PreRelease)
+	}
+
+	if v.Metadata != "" {
+		fmt.Fprintf(&buf, "+%s", v.Metadata)
+	}
+
+	return buf.String()
+}
+
+func (v Version) Number() string {
+	return fmt.Sprintf("%d.%d.%d", v.Major, v.Minor, v.Patch)
+}
+
+func Parse(v string) (Version, error) {
+	if !regexSemver.MatchString(v) {
+		return Version{}, fmt.Errorf("invalid version: %s", v)
+	}
+
+	match := regexSemver.FindStringSubmatch(v)
+	matchMap := make(map[string]string)
+	for i, name := range regexSemver.SubexpNames() {
+		if i != 0 && name != "" {
+			matchMap[name] = match[i]
+		}
+	}
+
+	var err error
+	var major int64
+	var minor int64
+	var patch int64
+	var preRelease PreRelease
+	var metadata Metadata
+
+	if major, err = strconv.ParseInt(matchMap["major"], 10, 64); err != nil {
+		return Version{}, err
+	}
+
+	if minor, err = strconv.ParseInt(matchMap["minor"], 10, 64); err != nil {
+		return Version{}, err
+	}
+
+	if patch, err = strconv.ParseInt(matchMap["patch"], 10, 64); err != nil {
+		return Version{}, err
+	}
+
+	if matchMap["prerelease"] != "" {
+		preRelease = PreRelease(matchMap["prerelease"])
+	}
+
+	if matchMap["buildmetadata"] != "" {
+		metadata = Metadata(matchMap["buildmetadata"])
+	}
+
+	return Version{
+		Major:      major,
+		Minor:      minor,
+		Patch:      patch,
+		PreRelease: preRelease,
+		Metadata:   metadata,
+	}, nil
+}

semver/version_test.go

@@ -0,0 +1,210 @@
+package semver
+
+import (
+	"reflect"
+	"testing"
+)
+
+var validVersionTests = []struct {
+	name     string
+	input    string
+	version  Version
+	inputErr bool
+	commit   string
+	date     string
+	release  string
+	full     string
+	number   string
+}{
+	{
+		name:  "stable",
+		input: "0.1.0",
+		version: Version{
+			Major: 0,
+			Minor: 1,
+		},
+		inputErr: false,
+		commit:   "",
+		date:     "",
+		release:  "stable",
+		full:     "0.1.0",
+		number:   "0.1.0",
+	},
+	{
+		name:  "stable.1",
+		input: "0.1.1",
+		version: Version{
+			Major: 0,
+			Minor: 1,
+			Patch: 1,
+		},
+		inputErr: false,
+		commit:   "",
+		date:     "",
+		release:  "stable",
+		full:     "0.1.1",
+		number:   "0.1.1",
+	},
+	{
+		name:  "stable.1+metadata",
+		input: "0.1.1+metadata",
+		version: Version{
+			Major:    0,
+			Minor:    1,
+			Patch:    1,
+			Metadata: "metadata",
+		},
+		inputErr: false,
+		commit:   "metadata",
+		date:     "metadata",
+		release:  "stable",
+		full:     "0.1.1+metadata",
+		number:   "0.1.1",
+	},
+	{
+		name:  "stable.1+metadata.date",
+		input: "0.1.1+metadata.20101112",
+		version: Version{
+			Major:    0,
+			Minor:    1,
+			Patch:    1,
+			Metadata: "metadata.20101112",
+		},
+		inputErr: false,
+		commit:   "metadata",
+		date:     "20101112",
+		release:  "stable",
+		full:     "0.1.1+metadata.20101112",
+		number:   "0.1.1",
+	},
+	{
+		name:  "alpha",
+		input: "0.1.1-alpha",
+		version: Version{
+			Major:      0,
+			Minor:      1,
+			Patch:      1,
+			PreRelease: "alpha",
+		},
+		inputErr: false,
+		commit:   "",
+		release:  "alpha",
+		full:     "0.1.1-alpha",
+		number:   "0.1.1",
+	},
+	{
+		name:  "alpha.1",
+		input: "0.1.1-alpha.1",
+		version: Version{
+			Major:      0,
+			Minor:      1,
+			Patch:      1,
+			PreRelease: "alpha.1",
+		},
+		inputErr: false,
+		commit:   "",
+		release:  "alpha.1",
+		full:     "0.1.1-alpha.1",
+		number:   "0.1.1",
+	},
+}
+
+func TestParse(t *testing.T) {
+	for _, tt := range validVersionTests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := Parse(tt.input)
+			if (err != nil) != tt.inputErr {
+				t.Errorf("Parse() error = %v, wantErr %v", err, tt.inputErr)
+				return
+			}
+			if !reflect.DeepEqual(got, tt.version) {
+				t.Errorf("Parse() got = %v, want %v", got, tt.version)
+			}
+		})
+	}
+}
+
+func TestVersion_Commit(t *testing.T) {
+	for _, tt := range validVersionTests {
+		t.Run(tt.name, func(t *testing.T) {
+			v := Version{
+				Major:      tt.version.Major,
+				Minor:      tt.version.Minor,
+				Patch:      tt.version.Patch,
+				PreRelease: tt.version.PreRelease,
+				Metadata:   tt.version.Metadata,
+			}
+			if got := v.Commit(); got != tt.commit {
+				t.Errorf("Commit() = %v, want %v", got, tt.commit)
+			}
+		})
+	}
+}
+
+func TestVersion_Date(t *testing.T) {
+	for _, tt := range validVersionTests {
+		t.Run(tt.name, func(t *testing.T) {
+			v := Version{
+				Major:      tt.version.Major,
+				Minor:      tt.version.Minor,
+				Patch:      tt.version.Patch,
+				PreRelease: tt.version.PreRelease,
+				Metadata:   tt.version.Metadata,
+			}
+			if got := v.Date(); got != tt.date {
+				t.Errorf("Date() = %v, want %v", got, tt.date)
+			}
+		})
+	}
+}
+
+func TestVersion_Release(t *testing.T) {
+	for _, tt := range validVersionTests {
+		t.Run(tt.name, func(t *testing.T) {
+			v := Version{
+				Major:      tt.version.Major,
+				Minor:      tt.version.Minor,
+				Patch:      tt.version.Patch,
+				PreRelease: tt.version.PreRelease,
+				Metadata:   tt.version.Metadata,
+			}
+			if got := v.Release(); got != tt.release {
+				t.Errorf("Release() = %v, want %v", got, tt.release)
+			}
+		})
+	}
+}
+
+func TestVersion_String(t *testing.T) {
+	for _, tt := range validVersionTests {
+		t.Run(tt.name, func(t *testing.T) {
+			v := Version{
+				Major:      tt.version.Major,
+				Minor:      tt.version.Minor,
+				Patch:      tt.version.Patch,
+				PreRelease: tt.version.PreRelease,
+				Metadata:   tt.version.Metadata,
+			}
+			if got := v.String(); got != tt.full {
+				t.Errorf("String() = %v, want %v", got, tt.full)
+			}
+		})
+	}
+}
+
+func TestVersion_VersionNumber(t *testing.T) {
+	for _, tt := range validVersionTests {
+		t.Run(tt.name, func(t *testing.T) {
+			v := Version{
+				Major:      tt.version.Major,
+				Minor:      tt.version.Minor,
+				Patch:      tt.version.Patch,
+				PreRelease: tt.version.PreRelease,
+				Metadata:   tt.version.Metadata,
+			}
+			if got := v.Number(); got != tt.number {
+				t.Errorf("Number() = %v, want %v", got, tt.number)
+			}
+		})
+	}
+}

slogd/disabledHandler.go

@@ -0,0 +1,32 @@
+package slogd
+
+import (
+	"context"
+	"log/slog"
+)
+
+func newDisabledHandler() slog.Handler {
+	return &disabledHandler{}
+}
+
+func registerDisabledHandler(activate bool) {
+	RegisterSink(handlerDisabled, newDisabledHandler(), activate)
+}
+
+type disabledHandler struct{}
+
+func (h *disabledHandler) Handle(ctx context.Context, r slog.Record) error {
+	return nil
+}
+
+func (h *disabledHandler) Enabled(ctx context.Context, level slog.Level) bool {
+	return false
+}
+
+func (h *disabledHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
+	return h
+}
+
+func (h *disabledHandler) WithGroup(group string) slog.Handler {
+	return h
+}

slogd/jsonHandler.go

@@ -0,0 +1,10 @@
+package slogd
+
+import (
+	"io"
+	"log/slog"
+)
+
+func RegisterJSONHandler(w io.Writer, activate bool) {
+	RegisterSink(HandlerJSON, slog.NewJSONHandler(w, HandlerOptions()), activate)
+}

slogd/level.go

@@ -0,0 +1,56 @@
+package slogd
+
+import (
+	"log/slog"
+	"strings"
+)
+
+const (
+	LevelTrace   = slog.Level(-8)
+	LevelDebug   = slog.LevelDebug
+	LevelInfo    = slog.LevelInfo
+	LevelNotice  = slog.Level(2)
+	LevelWarn    = slog.LevelWarn
+	LevelError   = slog.LevelError
+	LevelFatal   = slog.Level(12)
+	LevelDefault = LevelInfo
+)
+
+var levelNames = map[slog.Leveler]string{
+	LevelTrace:  "TRACE",
+	LevelDebug:  "DEBUG",
+	LevelInfo:   "INFO",
+	LevelNotice: "NOTICE",
+	LevelWarn:   "WARN",
+	LevelError:  "ERROR",
+	LevelFatal:  "FATAL",
+}
+
+func ReplaceAttrs(groups []string, a slog.Attr) slog.Attr {
+	if a.Key == slog.LevelKey {
+		a.Value = slog.StringValue(LevelName(a.Value.Any().(slog.Level)))
+	}
+	return a
+}
+
+func Level(l string) slog.Level {
+	mux.Lock()
+	defer mux.Unlock()
+	for k, v := range levelNames {
+		if strings.ToUpper(l) == v {
+			return k.Level()
+		}
+	}
+	return LevelDefault
+}
+
+func LevelName(l slog.Level) string {
+	mux.Lock()
+	defer mux.Unlock()
+	for k, v := range levelNames {
+		if k == l {
+			return v
+		}
+	}
+	return levelNames[LevelDefault]
+}

slogd/slogd.go

@@ -0,0 +1,148 @@
+package slogd
+
+import (
+	"context"
+	"log/slog"
+	"sync"
+
+	slogformatter "github.com/samber/slog-formatter"
+	slogmulti "github.com/samber/slog-multi"
+)
+
+const (
+	HandlerText     string = "text"
+	HandlerJSON     string = "json"
+	handlerDisabled string = "disabled"
+)
+
+const (
+	FlowFanOut Flow = iota
+	FlowPipeline
+	FlowRouting
+	FlowFailOver
+	FlowLoadBalancing
+)
+
+type Flow int
+
+var (
+	ctxKey = contextKey{}
+)
+var (
+	handlers      = make(map[string]slog.Handler)
+	activeHandler string
+	level         = new(slog.LevelVar)
+	formatters    []slogformatter.Formatter
+	middlewares   []slogmulti.Middleware
+	source        bool
+	logger        *slog.Logger
+	mux           = &sync.Mutex{}
+)
+
+func ActiveHandler() string {
+	mux.Lock()
+	defer mux.Unlock()
+	return activeHandler
+}
+
+func key() contextKey {
+	return ctxKey
+}
+
+func Disable() {
+	UseHandler(handlerDisabled)
+}
+
+func FromContext(ctx context.Context) *slog.Logger {
+	if l, ok := ctx.Value(key()).(*slog.Logger); ok {
+		return l
+	}
+	return Logger()
+}
+
+func GetLevel() slog.Level {
+	return level.Level()
+}
+
+func GetLevelString() string {
+	return level.String()
+}
+
+func HandlerOptions() *slog.HandlerOptions {
+	return &slog.HandlerOptions{
+		AddSource:   source,
+		Level:       level,
+		ReplaceAttr: ReplaceAttrs,
+	}
+}
+
+func Init(l slog.Level, addSource bool) {
+	level.Set(l)
+	source = addSource
+}
+
+func Logger() *slog.Logger {
+	mux.Lock()
+	defer mux.Unlock()
+
+	if logger == nil {
+		logger = slog.New(handlers[handlerDisabled])
+	}
+	return logger
+}
+
+func SetLevel(l slog.Level) {
+	mux.Lock()
+	defer mux.Unlock()
+	level.Set(l)
+}
+
+func RegisterFormatter(f slogformatter.Formatter) {
+	mux.Lock()
+	defer mux.Unlock()
+	formatters = append(formatters, f)
+}
+
+func RegisterMiddleware(h slogmulti.Middleware) {
+	mux.Lock()
+	defer mux.Unlock()
+	middlewares = append(middlewares, h)
+}
+
+func RegisterSink(name string, h slog.Handler, activate bool) {
+	mux.Lock()
+	handlers[name] = h
+	mux.Unlock()
+
+	if activate {
+		UseHandler(name)
+	}
+}
+
+func UseHandler(name string) {
+	mux.Lock()
+	defer mux.Unlock()
+	if _, ok := handlers[name]; !ok {
+		Logger().LogAttrs(context.Background(), LevelError, "could not find handler", slog.String("name", name))
+		return
+	}
+
+	formatterPipe := slogformatter.NewFormatterMiddleware(formatters...)
+	pipe := slogmulti.Pipe(middlewares...).Pipe(formatterPipe)
+	handler := slogmulti.Fanout(handlers[name])
+
+	logger = slog.New(pipe.Handler(handler))
+	activeHandler = name
+}
+
+func WithContext(ctx context.Context) context.Context {
+	return context.WithValue(ctx, key(), Logger())
+}
+
+func init() {
+	// RegisterFormatter(LevelFormatter())
+	// RegisterMiddleware(NewLevelMiddleware())
+	registerDisabledHandler(true)
+}
+
+type contextKey struct{}

slogd/textHandler.go

@@ -0,0 +1,10 @@
+package slogd
+
+import (
+	"io"
+	"log/slog"
+)
+
+func RegisterTextHandler(w io.Writer, activate bool) {
+	RegisterSink(HandlerText, slog.NewTextHandler(w, HandlerOptions()), activate)
+}

sqr/README.md

@@ -0,0 +1,135 @@
+# go-sql-sqr - SQL Query Repository for Go
+
+This library enables the use of centralized storage for all SQL queries used in an application.
+You can either choose to load all queries into a repository, or load them from a filesystem as necessary.
+
+The main intention is to embed a directory structure into the binary as ```embed.FS```, which can then used in the
+application.
+
+[![Go Reference](https://pkg.go.dev/badge/github.com/jantytgat/go-sql-sqr.svg)](https://pkg.go.dev/github.com/jantytgat/go-sql-sqr)
+
+---
+
+## Basics
+
+### Add the package to your project
+
+```bash
+go get git.flexabyte.io/flexabyte/go-kit
+```
+
+### Import
+Next, you can manually add the import statement to your ```.go```-file, or have it added automatically when using it.
+
+```text
+import git.flexabyte.io/flexabyte/go-kit/sqr
+```
+
+### Embed assets containing queries.
+
+> [!IMPORTANT]  
+> The root folder embedded in the application cannot have nested directories.  
+> This means that the directory structure is limited to 1 level of collections, each containing a set of text files with
+> a ```.sql``` extension.
+>
+> Files with another extension will fail to load!
+
+Let's assume to following directory structure in an embedded filesystem:
+
+```
+/assets
+|-- /queries
+    |-- collection1
+    |   |-- create.sql
+    |   |-- read.sql
+    |   |-- update.sql
+    |   |-- delete.sql
+    |-- collection2
+        |-- list.sql
+```
+
+You can now embed the statement files as follows:
+
+```go
+//go:embed assets/queries/*
+var f embed.FS
+```
+
+### With repository
+
+#### Create a new repository
+
+```go
+// Create query repository from embedded files
+var r *sqr.Repository
+if r, err = sqr.NewFromFs(f, "assets/queries"); err != nil {
+    panic(err)
+}
+```
+
+#### Load a query from the repository
+
+Now the repository has been initialized, we can get a query from a collection:
+
+```go
+var query string
+if query, err = r.Get("collection1", "create"); err != nil {
+    panic(err)
+}
+fmt.Println("Query:", query)
+```
+
+### Without repository
+
+If you don't want to initialize a repository, but rather choose to load SQL queries straight from the filesystem, you
+can do so as follows:
+
+```go
+var query string
+if query, err = sqr.LoadQueryFromFs(f, "assets/queries", "collection2", "list"); err != nil {
+    panic(err)
+}
+```
+
+## Prepared statements
+
+We also provide the means to create prepared statements for the queries, either with or without using a repository, as
+long as a ```Preparer``` is passed into the functions.
+
+```go
+type Preparer interface {
+	Prepare(query string) (*sql.Stmt, error)
+}
+```
+For example:
+
+- *sql.Db
+- *sql.Tx
+
+```go
+func Prepare[T Preparer](t T, r *Repository, collectionName, queryName string) (*sql.Stmt, error) {}
+func PrepareFromFs[T Preparer](t T, f fs.FS, rootPath, collectionName, queryName string) (*sql.Stmt, error) {}
+```
+
+### With repository
+
+```go
+var createStmt *sql.Stmt
+if createStmt, err = sqr.Prepare(db, r, "collection1", "create"); err != nil {
+    panic(err)
+}
+```
+
+### Without repository
+
+```go
+var createStmt *sql.Stmt
+if createStmt, err = sqr.PrepareFromFs(db, f, "assets/queries", "collection1", "create"); err != nil {
+    panic(err)
+}
+```
+
+## Examples
+Two examples are available:
+- embbededSqlWithRepository
+- embeddedSqlWithoutRepository

sqr/collection.go

@@ -0,0 +1,36 @@
+package sqr
+
+import (
+	"fmt"
+)
+
+// newCollection creates a new collection with the supplied name and returns it to the caller.
+func newCollection(name string) collection {
+	return collection{
+		name:    name,
+		queries: make(map[string]string),
+	}
+}
+
+type collection struct {
+	name    string
+	queries map[string]string
+}
+
+// add adds a query to the collection.
+func (c *collection) add(name, query string) error {
+	if _, ok := c.queries[name]; ok {
+		return fmt.Errorf("query %s already exists", name)
+	}
+	c.queries[name] = query
+	return nil
+}
+
+// get retrieves a query from the collection by name.
+// If the query name cannot be found, get() returns an empty string and an error.
+func (c *collection) get(name string) (string, error) {
+	if _, ok := c.queries[name]; !ok {
+		return "", fmt.Errorf("query %s not found in collection %s", name, c.name)
+	}
+	return c.queries[name], nil
+}

sqr/collection_test.go

@@ -0,0 +1,162 @@
+package sqr
+
+import (
+	"reflect"
+	"testing"
+)
+
+func Test_collection_add(t *testing.T) {
+	type fields struct {
+		name    string
+		queries map[string]string
+	}
+
+	type args struct {
+		name  string
+		query string
+	}
+
+	tests := []struct {
+		name    string
+		fields  fields
+		args    args
+		wantErr bool
+	}{
+		{
+			name: "good",
+			fields: fields{
+				name: "test1",
+				queries: map[string]string{
+					"query1": "queryString1",
+					"query2": "queryString2",
+				},
+			},
+			args: args{
+				name:  "query3",
+				query: "queryString3",
+			},
+			wantErr: false,
+		},
+		{
+			name: "bad",
+			fields: fields{
+				name: "test1",
+				queries: map[string]string{
+					"query1": "queryString1",
+					"query2": "queryString2",
+				},
+			},
+			args: args{
+				name:  "query2",
+				query: "queryString2",
+			},
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			c := &collection{
+				name:    tt.fields.name,
+				queries: tt.fields.queries,
+			}
+			if err := c.add(tt.args.name, tt.args.query); (err != nil) != tt.wantErr {
+				t.Errorf("add() error = %v, wantErr %v", err, tt.wantErr)
+			}
+		})
+	}
+}
+
+func Test_collection_get(t *testing.T) {
+	type fields struct {
+		name    string
+		queries map[string]string
+	}
+	type args struct {
+		name string
+	}
+	tests := []struct {
+		name    string
+		fields  fields
+		args    args
+		want    string
+		wantErr bool
+	}{
+		{
+			name: "good",
+			fields: fields{
+				name: "test1",
+				queries: map[string]string{
+					"query1": "queryString1",
+					"query2": "queryString2",
+				},
+			},
+			args: args{
+				name: "query1",
+			},
+			want:    "queryString1",
+			wantErr: false,
+		},
+		{
+			name: "bad",
+			fields: fields{
+				name: "test1",
+				queries: map[string]string{
+					"query1": "queryString1",
+					"query2": "queryString2",
+				},
+			},
+			args: args{
+				name: "query3",
+			},
+			want:    "",
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			c := &collection{
+				name:    tt.fields.name,
+				queries: tt.fields.queries,
+			}
+			got, err := c.get(tt.args.name)
+			if (err != nil) != tt.wantErr {
+				t.Errorf("get() error = %v, wantErr %v", err, tt.wantErr)
+				return
+			}
+			if got != tt.want {
+				t.Errorf("get() got = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+func Test_newCollection(t *testing.T) {
+	type args struct {
+		name string
+	}
+	tests := []struct {
+		name string
+		args args
+		want collection
+	}{
+		{
+			name: "test1",
+			args: args{
+				name: "test1",
+			},
+			want: collection{
+				name:    "test1",
+				queries: make(map[string]string),
+			},
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := newCollection(tt.args.name); !reflect.DeepEqual(got, tt.want) {
+				t.Errorf("newCollection() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}

sqr/loader.go

@@ -0,0 +1,30 @@
+package sqr
+
+import (
+	"embed"
+	"fmt"
+	"io/fs"
+	"path"
+	"path/filepath"
+)
+
+// LoadQueryFromFs retrieves a query from a filesystem.
+// It needs the root path to start the search from, as well as a collection name and a query name.
+// The collection name equals to a direct directory name in the root path.
+// The query name is the file name (without extension) to load the contents from.
+// It returns and empty string and an error if the file cannot be found.
+func LoadQueryFromFs(f fs.FS, rootPath, collectionName, queryName string) (string, error) {
+	var err error
+	var contents []byte
+	switch f.(type) {
+	case embed.FS:
+		if contents, err = fs.ReadFile(f, path.Join(rootPath, collectionName, queryName)+".sql"); err != nil {
+			return "", fmt.Errorf("failed to read file %s: %w", path.Join(rootPath, collectionName, queryName)+".sql", err)
+		}
+	default:
+		if contents, err = fs.ReadFile(f, filepath.Join(rootPath, collectionName, queryName)+".sql"); err != nil {
+			return "", fmt.Errorf("failed to read file %s: %w", filepath.Join(rootPath, collectionName, queryName)+".sql", err)
+		}
+	}
+	return string(contents), nil
+}

sqr/preparer.go

@@ -0,0 +1,76 @@
+package sqr
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"io/fs"
+)
+
+// Preparer defines the interface to create a prepared statement.
+type Preparer interface {
+	Prepare(query string) (*sql.Stmt, error)
+	PrepareContext(ctx context.Context, query string) (*sql.Stmt, error)
+}
+
+// Prepare creates a prepared statement for the supplied Preparer by looking up a query in the supplied repository.
+// It returns an nil pointer and an error if either the query cannot be found in the supplied repository, or the statement preparation fails.
+func Prepare[T Preparer](t T, r *Repository, collectionName, queryName string) (*sql.Stmt, error) {
+	if r == nil {
+		return nil, errors.New("repository is nil")
+	}
+
+	var err error
+	var query string
+
+	if query, err = r.Get(collectionName, queryName); err != nil {
+		return nil, err
+	}
+	return t.Prepare(query)
+}
+
+// Prepare creates a prepared statement for the supplied Preparer by looking up a query in the supplied repository using a context.
+// It returns an nil pointer and an error if either the query cannot be found in the supplied repository, or the statement preparation fails.
+func PrepareContext[T Preparer](ctx context.Context, t T, r *Repository, collectionName, queryName string) (*sql.Stmt, error) {
+	if r == nil {
+		return nil, errors.New("repository is nil")
+	}
+
+	var err error
+	var query string
+
+	if query, err = r.Get(collectionName, queryName); err != nil {
+		return nil, err
+	}
+	return t.PrepareContext(ctx, query)
+}
+
+// PrepareFromFs creates a prepared statement for the supplied Preparer by looking up a query in the supplied filesystem.
+// It returns an nil pointer and an error if either the query cannot be found in the supplied filesystem, or the statement preparation fails.
+func PrepareFromFs[T Preparer](t T, f fs.FS, rootPath, collectionName, queryName string) (*sql.Stmt, error) {
+	if f == nil {
+		return nil, errors.New("invalid filesystem")
+	}
+	var err error
+	var query string
+
+	if query, err = LoadQueryFromFs(f, rootPath, collectionName, queryName); err != nil {
+		return nil, err
+	}
+	return t.Prepare(query)
+}
+
+// PrepareFromFs creates a prepared statement for the supplied Preparer by looking up a query in the supplied filesystem using a context.
+// It returns an nil pointer and an error if either the query cannot be found in the supplied filesystem, or the statement preparation fails.
+func PrepareFromFsContext[T Preparer](ctx context.Context, t T, f fs.FS, rootPath, collectionName, queryName string) (*sql.Stmt, error) {
+	if f == nil {
+		return nil, errors.New("invalid filesystem")
+	}
+	var err error
+	var query string
+
+	if query, err = LoadQueryFromFs(f, rootPath, collectionName, queryName); err != nil {
+		return nil, err
+	}
+	return t.PrepareContext(ctx, query)
+}

sqr/repository.go

@@ -0,0 +1,191 @@
+// Package queryrepo enables the use of centralized storage for all SQL queries used in an application.
+package sqr
+
+import (
+	"context"
+	"database/sql"
+	"embed"
+	"errors"
+	"fmt"
+	"io/fs"
+	"path"
+	"path/filepath"
+	"strings"
+	"sync"
+)
+
+// NewFromFs creates a new repository using a filesystem.
+// It takes a filesystem and a root path to start loading files from and returns an error if files cannot be loaded.
+func NewFromFs(f fs.FS, rootPath string) (*Repository, error) {
+	repo := &Repository{
+		queries: make(map[string]collection),
+	}
+
+	return repo, loadFromFs(repo, f, rootPath)
+}
+
+// A Repository stores multiple collections of queries in a map for later use.
+// Queries can either be retrieved by their name, or be used to create a prepared statement.
+type Repository struct {
+	queries map[string]collection
+	mux     sync.Mutex
+}
+
+// add adds the supplied collection to the repository.
+// It returns an error if the collection already exists.
+func (r *Repository) add(c collection) error {
+	r.mux.Lock()
+	defer r.mux.Unlock()
+
+	if _, ok := r.queries[c.name]; ok {
+		return fmt.Errorf("collection %s already exists", c.name)
+	}
+	r.queries[c.name] = c
+	return nil
+}
+
+// DbPrepare creates a prepared statement for the supplied database handle.
+// It takes a collection name and query name to look up the query to create the prepared statement.
+func (r *Repository) DbPrepare(db *sql.DB, collectionName, queryName string) (*sql.Stmt, error) {
+	if db == nil {
+		return nil, errors.New("db is nil")
+	}
+
+	var err error
+	var query string
+
+	if query, err = r.Get(collectionName, queryName); err != nil {
+		return nil, err
+	}
+	return db.Prepare(query)
+}
+
+// DbPrepareContext creates a prepared statement for the supplied database handle using a context.
+// It takes a collection name and query name to look up the query to create the prepared statement.
+func (r *Repository) DbPrepareContext(ctx context.Context, db *sql.DB, collectionName, queryName string) (*sql.Stmt, error) {
+	if db == nil {
+		return nil, errors.New("db is nil")
+	}
+
+	var err error
+	var query string
+
+	if query, err = r.Get(collectionName, queryName); err != nil {
+		return nil, err
+	}
+
+	return db.PrepareContext(ctx, query)
+}
+
+// Get retrieves the supplied query from the repository.
+// It takes a collection name and a query name to perform the lookup and returns an empty string and an error if the query cannot be found
+// in the collection.
+func (r *Repository) Get(collectionName, queryName string) (string, error) {
+	r.mux.Lock()
+	defer r.mux.Unlock()
+
+	if s, ok := r.queries[collectionName]; ok {
+		return s.get(queryName)
+	}
+	return "", fmt.Errorf("collection %s not found", collectionName)
+}
+
+// TxPrepare creates a prepared statement for the supplied in-progress database transaction.
+// It takes a collection name and query name to look up the query to create the prepared statement.
+func (r *Repository) TxPrepare(tx *sql.Tx, collectionName, queryName string) (*sql.Stmt, error) {
+	if tx == nil {
+		return nil, errors.New("tx is nil")
+	}
+	var err error
+	var statement string
+
+	if statement, err = r.Get(collectionName, queryName); err != nil {
+		return nil, err
+	}
+
+	return tx.Prepare(statement)
+}
+
+// TxPrepare creates a prepared statement for the supplied in-progress database transaction using a context.
+// It takes a collection name and query name to look up the query to create the prepared statement.
+func (r *Repository) TxPrepareContext(ctx context.Context, tx *sql.Tx, collectionName, queryName string) (*sql.Stmt, error) {
+	if tx == nil {
+		return nil, errors.New("tx is nil")
+	}
+	var err error
+	var statement string
+
+	if statement, err = r.Get(collectionName, queryName); err != nil {
+		return nil, err
+	}
+
+	return tx.PrepareContext(ctx, statement)
+}
+
+// loadFromFs looks for directories in the root path to create collections for.
+// If a directory is found, it loads all the files in the subdirectory and adds the returned collection to the repository.
+func loadFromFs(r *Repository, f fs.FS, rootPath string) error {
+	if r == nil {
+		return errors.New("repository is nil")
+	}
+
+	if f == nil {
+		return errors.New("filesystem is nil")
+	}
+
+	var err error
+	var files []fs.DirEntry
+	if files, err = fs.ReadDir(f, rootPath); err != nil {
+		return err
+	}
+
+	for _, file := range files {
+		if file.IsDir() {
+			var c collection
+			if c, err = loadFilesFromDir(f, rootPath, file.Name()); err != nil {
+				return err
+			}
+
+			if err = r.add(c); err != nil {
+				return err
+			}
+		}
+	}
+	return nil
+}
+
+// loadFilesFromDir loads all the files in the directory and returns a collection of queries.
+func loadFilesFromDir(f fs.FS, rootPath, dirName string) (collection, error) {
+	var err error
+	var c = newCollection(dirName)
+	var fullPath string
+
+	switch f.(type) {
+	case embed.FS:
+		fullPath = path.Join(rootPath, dirName)
+	default:
+		fullPath = filepath.Join(rootPath, dirName)
+
+	}
+
+	var files []fs.DirEntry
+	if files, err = fs.ReadDir(f, fullPath); err != nil {
+		return c, err
+	}
+
+	for _, file := range files {
+		if file.IsDir() {
+			return c, fmt.Errorf("nested directories are not supported, %s is a directory in %s", file.Name(), fullPath)
+		}
+
+		var contents string
+		if contents, err = LoadQueryFromFs(f, rootPath, dirName, strings.TrimSuffix(file.Name(), filepath.Ext(file.Name()))); err != nil {
+			return c, err
+		}
+
+		if err = c.add(strings.TrimSuffix(file.Name(), filepath.Ext(file.Name())), contents); err != nil {
+			return c, err
+		}
+	}
+	return c, nil
+}