dbgorm

package

v0.1.32 Latest Latest Go to latest Published: Jul 16, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/phcp-tech/common-library-golang

Links

Open Source Insights

README ¶

dbgorm

dbgorm is a thin wrapper around GORM. It does not replace GORM, hide *gorm.DB, or provide a repository framework. Its main purpose is to make database initialization consistent while keeping normal database operations in plain GORM.

Features

Common GORM configuration and connection pool setup.
Optional process-wide default database instance.
Driver adapters for MySQL, PostgreSQL, and SQLite.
Small helpers for common read/delete/not-found patterns.
GORM scopes for pagination and allow-listed sorting.
Raw SQL helpers with parameter binding.
Optional migration helper.

Package Layout

The root package does not import concrete database drivers:

import dbgorm "github.com/phcp-tech/common-library-golang/dbgorm"

Concrete drivers live in adapter packages:

import "github.com/phcp-tech/common-library-golang/dbgorm/mysql"
import "github.com/phcp-tech/common-library-golang/dbgorm/postgres"
import "github.com/phcp-tech/common-library-golang/dbgorm/sqlite"

This keeps the root package independent from driver imports. Applications should only import the adapter packages they actually use.

The adapter packages expose flat config structs for application code. The root package only keeps the lower-level GormConfig used by adapters and by callers that already have a gorm.Dialector.

Install

This package is part of github.com/phcp-tech/common-library-golang.

go get github.com/phcp-tech/common-library-golang

If your application uses a specific adapter, make sure the matching GORM driver is available in the application module:

go get gorm.io/driver/mysql
go get gorm.io/driver/postgres
go get gorm.io/driver/sqlite

Opening a Database

MySQL

package main

import (
    "github.com/phcp-tech/common-library-golang/dbgorm/mysql"
    "gorm.io/gorm"
)

func openMySQL() (*gorm.DB, error) {
    return mysql.NewMySQL(mysql.Config{
        Host:            "localhost",
        Port:            "3306",
        Database:        "risk",
        Username:        "risk",
        Password:        "secret",
        MaxOpenConns:    50,
        MaxIdleConns:    10,
        ConnMaxLifetime: 60,
        ConnMaxIdletime: 10,
    })
}

PostgreSQL

db, err := postgres.NewPostgres(postgres.Config{
    Host:            "localhost",
    Port:            "5432",
    Database:        "risk",
    Username:        "risk",
    Password:        "secret",
    SearchPath:      "public",
    MaxOpenConns:    50,
    MaxIdleConns:    10,
    ConnMaxLifetime: 60,
    ConnMaxIdletime: 10,
})

SQLite

db, err := sqlite.NewSQLite(sqlite.Config{
    Path: "file:risk.db?cache=shared",
})

SQLite always opens through dbgorm.Open with MaxOpenConns and MaxIdleConns set to 1 to reduce database is locked errors. Its adapter config accepts only Path and optional Logger.

For tests:

db, err := sqlite.NewSQLite(sqlite.Config{
    Path: "file::memory:?cache=shared",
})

Low-level Open

Use dbgorm.Open only when you already have a gorm.Dialector:

db, err := dbgorm.Open(dialector, &dbgorm.GormConfig{
    MaxOpenConns:    50,
    MaxIdleConns:    10,
    ConnMaxLifetime: 60,
    ConnMaxIdletime: 10,
    Logger:          slog.Default(),
})

ConnMaxLifetime and ConnMaxIdletime are expressed in minutes. If a GormConfig field is zero, dbgorm.Open uses the library default.

Default Instance

Use the default instance when the process has one primary database connection.

if err := mysql.InitDefault(mysql.Config{
    Host:     "localhost",
    Port:     "3306",
    Database: "risk",
    Username: "risk",
    Password: "secret",
}); err != nil {
    return err
}

db := dbgorm.Default()

The default instance is process-wide. It is not one default per driver. If an application uses multiple databases, prefer explicit *gorm.DB fields:

type Store struct {
    MainDB    *gorm.DB
    MetricsDB *gorm.DB
}

Useful default-instance helpers:

db := dbgorm.Default()
dbgorm.SetDefault(db)

Applications should close or ping the default database through the returned *gorm.DB:

db := dbgorm.Default()
if db != nil {
    sqlDB, err := db.DB()
    if err != nil {
        return err
    }
    if err := sqlDB.PingContext(ctx); err != nil {
        return err
    }
    defer sqlDB.Close()
}

Logging

By default, Open configures GORM SQL logging with the standard library slog.Default() logger.

To use the project logger, pass its *slog.Logger through Config.Logger:

import applog "github.com/phcp-tech/common-library-golang/log"

db, err := mysql.NewMySQL(mysql.Config{
    Host:     "localhost",
    Port:     "3306",
    Database: "risk",
    Username: "risk",
    Password: "secret",
    Logger:   applog.Instance().Logger,
})

To inspect the logger formats used by the package tests, run:

go test -count=1 -v ./dbgorm -run "TestOpenUses(DefaultSlogLogger|LibraryLogInstance)"

TestOpenUsesDefaultSlogLogger prints the JSON output captured from slog.Default(). TestOpenUsesLibraryLogInstance triggers the JSON slog handler configured by library-golang/log/slog.go.

Normal GORM Usage

After opening a database, use standard GORM APIs directly:

err := db.WithContext(ctx).Create(&user).Error

err := db.WithContext(ctx).
    Where("status = ?", "active").
    Order("created_at desc").
    Find(&users).Error

Transactions stay as normal GORM transactions:

err := db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
    if err := tx.Create(&order).Error; err != nil {
        return err
    }

    return dbgorm.DeleteWhere(ctx, tx, &CartItem{}, "user_id = ?", userID)
})

Helper Functions

Find by ID

user, err := dbgorm.FirstByID[User](ctx, db, userID)
if err != nil {
    if dbgorm.IsNotFound(err) {
        return nil, ErrUserNotFound
    }
    return nil, err
}

Find by Condition

user, err := dbgorm.FirstWhere[User](ctx, db, "email = ?", email)

Delete by ID

DeleteByID returns gorm.ErrRecordNotFound when no row is deleted.

err := dbgorm.DeleteByID[User](ctx, db, userID)
if dbgorm.IsNotFound(err) {
    return ErrUserNotFound
}

Delete by Condition

DeleteWhere treats zero affected rows as success.

err := dbgorm.DeleteWhere(ctx, db, &Session{}, "expires_at < ?", cutoff)

Pagination and Sorting

Use scopes for reusable query modifiers:

allowedSorts := map[string]string{
    "id":        "id",
    "createdAt": "created_at",
    "email":     "email",
}

err := db.WithContext(ctx).
    Scopes(
        dbgorm.OrderBy(allowedSorts, req.Sort, req.Direction),
        dbgorm.Paginate(req.Page, req.Limit),
    ).
    Find(&users).Error

OrderBy only accepts columns listed in the allow-list. This avoids directly injecting request values into ORDER BY.

Raw SQL

Use raw SQL helpers when a query is easier to express manually. Always pass values through arguments instead of string concatenation.

rows, err := dbgorm.ExecRaw(
    ctx,
    db,
    "update users set status = ? where id = ?",
    "disabled",
    userID,
)

var total int64
err := dbgorm.ScanRaw(
    ctx,
    db,
    &total,
    "select count(*) from users where status = ?",
    "active",
)

Error Handling

Use IsNotFound to check for GORM's not-found condition:

if dbgorm.IsNotFound(err) {
    // map to 404, domain error, or another application-specific response
}

Common package errors:

dbgorm.ErrNilDialector
dbgorm.ErrMissingConfig

Configuration Ownership

dbgorm does not read application environment variables. Load config in the application, then build the adapter config explicitly:

db, err := mysql.NewMySQL(mysql.Config{
    Host:            env.DBHost,
    Port:            env.DBPort,
    Database:        env.DBName,
    Username:        env.DBUser,
    Password:        env.DBPassword,
    MaxOpenConns:    env.DBMaxOpenConns,
    MaxIdleConns:    env.DBMaxIdleConns,
    ConnMaxLifetime: env.DBConnMaxLifetime,
    ConnMaxIdletime: env.DBConnMaxIdletime,
    Logger:          appLogger,
})

Testing

SQLite in-memory is convenient for tests:

db, err := sqlite.NewSQLite(sqlite.Config{
    Path: "file::memory:?cache=shared",
})

Run package tests:

go test ./dbgorm/...

Documentation ¶

Index ¶

Constants
Variables
func AutoMigrate(ctx context.Context, db *gorm.DB, models ...any) error
func Close(db *gorm.DB) error
func Create[T any](ctx context.Context, db *gorm.DB, record *T) (*T, error)
func Default() *gorm.DB
func DeleteByID[T any](ctx context.Context, db *gorm.DB, id any) error
func DeleteWhere(ctx context.Context, db *gorm.DB, model any, query any, args ...any) error
func ExecRaw(ctx context.Context, db *gorm.DB, sql string, args ...any) (int64, error)
func FirstByID[T any](ctx context.Context, db *gorm.DB, id any) (*T, error)
func FirstWhere[T any](ctx context.Context, db *gorm.DB, query any, args ...any) (*T, error)
func HealthChecker() health.Checker
func IsNotFound(err error) bool
func IsSafeSQLIdentifierPath(value string) bool
func IsSafeSQLName(value string) bool
func NormalizeSortDirection(direction string) string
func Open(dialector gorm.Dialector, conf *GormConfig) (*gorm.DB, error)
func OrderBy(allowed map[string]string, sort, direction string) func(*gorm.DB) *gorm.DB
func PageSql(para *dto.PageParameter) string
func Paginate(page, limit int) func(*gorm.DB) *gorm.DB
func ScanRaw(ctx context.Context, db *gorm.DB, dest any, sql string, args ...any) error
func SetDefault(db *gorm.DB)
func SortSql(para *dto.PageParameter) string
func UpdateByID[T any](ctx context.Context, db *gorm.DB, id any, values any) error
func UpdateWhere(ctx context.Context, db *gorm.DB, model any, values any, query any, ...) error
type GormConfig

Constants ¶

View Source

const (
	MaxOpenConns    = 100              // MaxOpenConns is the maximum number of open database connections in the pool.
	MaxIdleConns    = 25               // MaxIdleConns is the maximum number of idle database connections (1/4 of MaxOpenConns).
	ConnMaxLifetime = 60 * time.Minute // ConnMaxLifetime is the maximum lifetime of a database connection in minutes.
	ConnMaxIdletime = 10 * time.Minute // ConnMaxIdletime is the maximum idle lifetime of a database connection in minutes.
)

Variables ¶

View Source

var (
	// ErrNilDialector is returned when Open receives a nil GORM dialector.
	ErrNilDialector = errors.New("dbgorm: nil gorm dialector")
	// ErrMissingConfig is returned when an adapter lacks required connection fields.
	ErrMissingConfig = errors.New("dbgorm: missing connection fields")
)

Functions ¶

func AutoMigrate ¶ added in v0.1.23

func AutoMigrate(ctx context.Context, db *gorm.DB, models ...any) error

AutoMigrate runs GORM auto-migration for all provided model types.

Example ¶

ExampleAutoMigrate shows how to create database tables from GORM model structs. Pass all models in a single call; AutoMigrate creates or updates each table in order.

package main

import (
	"context"
	"fmt"

	libgorm "github.com/phcp-tech/common-library-golang/dbgorm"
	"github.com/phcp-tech/common-library-golang/dbgorm/sqlite"
)

func main() {
	ctx := context.Background()
	dialector, _ := sqlite.Dialector(&sqlite.Config{Path: ":memory:"})
	db, _ := libgorm.Open(dialector, &libgorm.GormConfig{MaxOpenConns: 1})

	type Article struct {
		ID    uint `gorm:"primaryKey"`
		Title string
	}
	type Tag struct {
		ID   uint `gorm:"primaryKey"`
		Name string
	}

	err := libgorm.AutoMigrate(ctx, db, &Article{}, &Tag{})
	fmt.Println(err == nil)
	fmt.Println(db.Migrator().HasTable(&Article{}))
	fmt.Println(db.Migrator().HasTable(&Tag{}))
}

Output:
true
true
true

func Close ¶

func Close(db *gorm.DB) error

Close closes the underlying database/sql connection for db.

Example ¶

ExampleClose shows how to close a GORM database obtained from an adapter. Close is a no-op when db is nil.

package main

import (
	"fmt"

	libgorm "github.com/phcp-tech/common-library-golang/dbgorm"
	"github.com/phcp-tech/common-library-golang/dbgorm/sqlite"

	"gorm.io/gorm"
)

// exProduct is a minimal GORM model used by the example functions.
type exProduct struct {
	ID       uint `gorm:"primaryKey"`
	Name     string
	Category string
}

// exDB opens a private in-memory SQLite database and migrates exProduct.
// Each call returns an independent database — no shared state between examples.
func exDB() *gorm.DB {
	db, err := sqlite.NewSQLite(&sqlite.Config{Path: ":memory:"})
	if err != nil {
		panic("exDB: " + err.Error())
	}
	if err := db.AutoMigrate(&exProduct{}); err != nil {
		panic("exDB migrate: " + err.Error())
	}
	return db
}

func main() {
	db := exDB()
	err := libgorm.Close(db)
	fmt.Println(err == nil)
}

Output:
true

func Create ¶ added in v0.1.23

func Create[T any](ctx context.Context, db *gorm.DB, record *T) (*T, error)

Create inserts record into the database and returns the created record. The returned pointer reflects auto-populated fields (primary key, timestamps, etc.).

Example ¶

ExampleCreate shows how to insert a new record and retrieve its auto-populated fields.

package main

import (
	"context"
	"fmt"

	libgorm "github.com/phcp-tech/common-library-golang/dbgorm"
	"github.com/phcp-tech/common-library-golang/dbgorm/sqlite"

	"gorm.io/gorm"
)

// exProduct is a minimal GORM model used by the example functions.
type exProduct struct {
	ID       uint `gorm:"primaryKey"`
	Name     string
	Category string
}

// exDB opens a private in-memory SQLite database and migrates exProduct.
// Each call returns an independent database — no shared state between examples.
func exDB() *gorm.DB {
	db, err := sqlite.NewSQLite(&sqlite.Config{Path: ":memory:"})
	if err != nil {
		panic("exDB: " + err.Error())
	}
	if err := db.AutoMigrate(&exProduct{}); err != nil {
		panic("exDB migrate: " + err.Error())
	}
	return db
}

func main() {
	ctx := context.Background()
	db := exDB()

	created, err := libgorm.Create(ctx, db, &exProduct{Name: "chisel", Category: "tools"})
	fmt.Println(err == nil)
	fmt.Println(created.ID > 0) // primary key populated by the database
	fmt.Println(created.Name)
}

Output:
true
true
chisel

func Default ¶

func Default() *gorm.DB

Default returns the process-wide default GORM database instance.

Example ¶

ExampleDefault shows how to retrieve the process-wide default *gorm.DB.

package main

import (
	"fmt"

	libgorm "github.com/phcp-tech/common-library-golang/dbgorm"
)

func main() {
	prev := libgorm.Default()
	libgorm.SetDefault(nil)
	defer libgorm.SetDefault(prev) // restore after example

	fmt.Println(libgorm.Default() == nil) // nil — not yet initialised
}

Output:
true

func DeleteByID ¶

func DeleteByID[T any](ctx context.Context, db *gorm.DB, id any) error

DeleteByID deletes the record of type T matching the primary key id.

Example ¶

ExampleDeleteByID shows how to delete a record by primary key. Returns gorm.ErrRecordNotFound when no row is deleted.

package main

import (
	"context"
	"fmt"

	libgorm "github.com/phcp-tech/common-library-golang/dbgorm"
	"github.com/phcp-tech/common-library-golang/dbgorm/sqlite"

	"gorm.io/gorm"
)

// exProduct is a minimal GORM model used by the example functions.
type exProduct struct {
	ID       uint `gorm:"primaryKey"`
	Name     string
	Category string
}

// exDB opens a private in-memory SQLite database and migrates exProduct.
// Each call returns an independent database — no shared state between examples.
func exDB() *gorm.DB {
	db, err := sqlite.NewSQLite(&sqlite.Config{Path: ":memory:"})
	if err != nil {
		panic("exDB: " + err.Error())
	}
	if err := db.AutoMigrate(&exProduct{}); err != nil {
		panic("exDB migrate: " + err.Error())
	}
	return db
}

func main() {
	ctx := context.Background()
	db := exDB()
	p := &exProduct{Name: "bolt"}
	db.Create(p)

	err := libgorm.DeleteByID[exProduct](ctx, db, p.ID)
	fmt.Println(err == nil)

	// Deleting again returns not-found.
	fmt.Println(libgorm.IsNotFound(libgorm.DeleteByID[exProduct](ctx, db, p.ID)))
}

Output:
true
true

func DeleteWhere ¶

func DeleteWhere(ctx context.Context, db *gorm.DB, model any, query any, args ...any) error

DeleteWhere deletes records for model matching query and args.

Example ¶

ExampleDeleteWhere shows how to delete all records matching a condition. Zero affected rows is treated as success.

package main

import (
	"context"
	"fmt"

	libgorm "github.com/phcp-tech/common-library-golang/dbgorm"
	"github.com/phcp-tech/common-library-golang/dbgorm/sqlite"

	"gorm.io/gorm"
)

// exProduct is a minimal GORM model used by the example functions.
type exProduct struct {
	ID       uint `gorm:"primaryKey"`
	Name     string
	Category string
}

// exDB opens a private in-memory SQLite database and migrates exProduct.
// Each call returns an independent database — no shared state between examples.
func exDB() *gorm.DB {
	db, err := sqlite.NewSQLite(&sqlite.Config{Path: ":memory:"})
	if err != nil {
		panic("exDB: " + err.Error())
	}
	if err := db.AutoMigrate(&exProduct{}); err != nil {
		panic("exDB migrate: " + err.Error())
	}
	return db
}

func main() {
	ctx := context.Background()
	db := exDB()
	db.Create(&exProduct{Name: "nail", Category: "fasteners"})
	db.Create(&exProduct{Name: "screw", Category: "fasteners"})

	err := libgorm.DeleteWhere(ctx, db, &exProduct{}, "category = ?", "fasteners")
	fmt.Println(err == nil)
}

Output:
true

func ExecRaw ¶

func ExecRaw(ctx context.Context, db *gorm.DB, sql string, args ...any) (int64, error)

ExecRaw executes a raw SQL statement with positional arguments.

Example ¶

ExampleExecRaw shows how to execute a raw SQL statement with positional args.

package main

import (
	"context"
	"fmt"

	libgorm "github.com/phcp-tech/common-library-golang/dbgorm"
	"github.com/phcp-tech/common-library-golang/dbgorm/sqlite"

	"gorm.io/gorm"
)

// exProduct is a minimal GORM model used by the example functions.
type exProduct struct {
	ID       uint `gorm:"primaryKey"`
	Name     string
	Category string
}

// exDB opens a private in-memory SQLite database and migrates exProduct.
// Each call returns an independent database — no shared state between examples.
func exDB() *gorm.DB {
	db, err := sqlite.NewSQLite(&sqlite.Config{Path: ":memory:"})
	if err != nil {
		panic("exDB: " + err.Error())
	}
	if err := db.AutoMigrate(&exProduct{}); err != nil {
		panic("exDB migrate: " + err.Error())
	}
	return db
}

func main() {
	ctx := context.Background()
	db := exDB()
	p := &exProduct{Name: "gear", Category: "parts"}
	db.Create(p)

	rows, err := libgorm.ExecRaw(ctx, db,
		"UPDATE ex_products SET category = ? WHERE id = ?", "machinery", p.ID)
	fmt.Println(err == nil)
	fmt.Println(rows) // 1 row updated
}

Output:
true
1

func FirstByID ¶

func FirstByID[T any](ctx context.Context, db *gorm.DB, id any) (*T, error)

FirstByID returns the first record of type T matching the primary key id.

Example ¶

ExampleFirstByID shows how to fetch a record by primary key. Returns gorm.ErrRecordNotFound when no row matches.

package main

import (
	"context"
	"fmt"

	libgorm "github.com/phcp-tech/common-library-golang/dbgorm"
	"github.com/phcp-tech/common-library-golang/dbgorm/sqlite"

	"gorm.io/gorm"
)

// exProduct is a minimal GORM model used by the example functions.
type exProduct struct {
	ID       uint `gorm:"primaryKey"`
	Name     string
	Category string
}

// exDB opens a private in-memory SQLite database and migrates exProduct.
// Each call returns an independent database — no shared state between examples.
func exDB() *gorm.DB {
	db, err := sqlite.NewSQLite(&sqlite.Config{Path: ":memory:"})
	if err != nil {
		panic("exDB: " + err.Error())
	}
	if err := db.AutoMigrate(&exProduct{}); err != nil {
		panic("exDB migrate: " + err.Error())
	}
	return db
}

func main() {
	ctx := context.Background()
	db := exDB()
	p := &exProduct{Name: "widget", Category: "tools"}
	db.Create(p)

	found, err := libgorm.FirstByID[exProduct](ctx, db, p.ID)
	fmt.Println(err == nil)
	fmt.Println(found.Name)
}

Output:
true
widget

func FirstWhere ¶

func FirstWhere[T any](ctx context.Context, db *gorm.DB, query any, args ...any) (*T, error)

FirstWhere returns the first record of type T matching query and args.

Example ¶

ExampleFirstWhere shows how to fetch the first record matching a condition.

package main

import (
	"context"
	"fmt"

	libgorm "github.com/phcp-tech/common-library-golang/dbgorm"
	"github.com/phcp-tech/common-library-golang/dbgorm/sqlite"

	"gorm.io/gorm"
)

// exProduct is a minimal GORM model used by the example functions.
type exProduct struct {
	ID       uint `gorm:"primaryKey"`
	Name     string
	Category string
}

// exDB opens a private in-memory SQLite database and migrates exProduct.
// Each call returns an independent database — no shared state between examples.
func exDB() *gorm.DB {
	db, err := sqlite.NewSQLite(&sqlite.Config{Path: ":memory:"})
	if err != nil {
		panic("exDB: " + err.Error())
	}
	if err := db.AutoMigrate(&exProduct{}); err != nil {
		panic("exDB migrate: " + err.Error())
	}
	return db
}

func main() {
	ctx := context.Background()
	db := exDB()
	db.Create(&exProduct{Name: "hammer", Category: "tools"})
	db.Create(&exProduct{Name: "wrench", Category: "tools"})

	found, err := libgorm.FirstWhere[exProduct](ctx, db, "name = ?", "wrench")
	fmt.Println(err == nil)
	fmt.Println(found.Name)
}

Output:
true
wrench

func HealthChecker ¶

func HealthChecker() health.Checker

HealthChecker returns a health.Checker that verifies database connectivity by pinging the default GORM database.

The Checker is dialect-agnostic — it works with any driver (MySQL, PostgreSQL, SQLite, …) that was used to initialise Default. Reports health.StatusUnhealthy when Default() is nil or when the ping fails; health.StatusHealthy when reachable.

Example ¶

ExampleHealthChecker shows how to wire HealthChecker into a health.Check call for a /health HTTP endpoint.

package main

import (
	"context"
	"fmt"

	libgorm "github.com/phcp-tech/common-library-golang/dbgorm"

	"github.com/phcp-tech/common-library-golang/health"
)

func main() {
	prev := libgorm.Default()
	libgorm.SetDefault(nil)
	defer libgorm.SetDefault(prev)

	results := health.Check(context.Background(), libgorm.HealthChecker())
	fmt.Println(results[0].Name)
	fmt.Println(results[0].Status == health.StatusUnhealthy) // true — Default() is nil
}

Output:
database
true

func IsNotFound ¶

func IsNotFound(err error) bool

IsNotFound reports whether err represents GORM's record-not-found condition.

Example ¶

ExampleIsNotFound shows how to distinguish a not-found error from other database errors. Use it instead of comparing directly against gorm.ErrRecordNotFound.

package main

import (
	"context"
	"fmt"

	libgorm "github.com/phcp-tech/common-library-golang/dbgorm"
	"github.com/phcp-tech/common-library-golang/dbgorm/sqlite"

	"gorm.io/gorm"
)

// exProduct is a minimal GORM model used by the example functions.
type exProduct struct {
	ID       uint `gorm:"primaryKey"`
	Name     string
	Category string
}

// exDB opens a private in-memory SQLite database and migrates exProduct.
// Each call returns an independent database — no shared state between examples.
func exDB() *gorm.DB {
	db, err := sqlite.NewSQLite(&sqlite.Config{Path: ":memory:"})
	if err != nil {
		panic("exDB: " + err.Error())
	}
	if err := db.AutoMigrate(&exProduct{}); err != nil {
		panic("exDB migrate: " + err.Error())
	}
	return db
}

func main() {
	ctx := context.Background()
	db := exDB()

	_, err := libgorm.FirstByID[exProduct](ctx, db, 9999)
	fmt.Println(libgorm.IsNotFound(err)) // true — no row with id=9999
}

Output:
true

func IsSafeSQLIdentifierPath ¶ added in v0.1.26

func IsSafeSQLIdentifierPath(value string) bool

IsSafeSQLIdentifierPath reports whether value is a dot-separated path of safe SQL identifiers (e.g. "table.column"), guarding SortSql against injection via the Sort field. Exported so dialect packages building their own ORDER BY expressions (e.g. ChineseSortSql in dbgorm/postgres, dbgorm/mysql) can validate a column name with the same rules.

func IsSafeSQLName ¶ added in v0.1.26

func IsSafeSQLName(value string) bool

IsSafeSQLName reports whether value is a safe single SQL identifier: letters, digits (not leading), and underscores only. Also usable to validate a charset/encoding name interpolated directly into SQL (e.g. by ChineseSortSql), since it follows the same safe-token shape.

func NormalizeSortDirection ¶ added in v0.1.26

func NormalizeSortDirection(direction string) string

NormalizeSortDirection returns direction upper-cased and trimmed, falling back to "ASC" when it is empty or not one of "ASC"/"DESC". Exported so dialect packages building their own ORDER BY expressions (e.g. ChineseSortSql in dbgorm/postgres, dbgorm/mysql) apply the exact same direction rules SortSql does.

func Open ¶

func Open(dialector gorm.Dialector, conf *GormConfig) (*gorm.DB, error)

Open opens a GORM database using the supplied dialector and common config.

Example ¶

ExampleOpen shows the low-level Open API using a GORM dialector directly. Prefer the adapter packages (dbgorm/mysql, dbgorm/postgres, dbgorm/sqlite) for application code.

package main

import (
	"fmt"

	libgorm "github.com/phcp-tech/common-library-golang/dbgorm"
	"github.com/phcp-tech/common-library-golang/dbgorm/sqlite"
)

func main() {
	dialector, _ := sqlite.Dialector(&sqlite.Config{Path: ":memory:"})
	db, err := libgorm.Open(dialector, &libgorm.GormConfig{
		MaxOpenConns: 1,
		MaxIdleConns: 1,
	})
	fmt.Println(err == nil)
	fmt.Println(db != nil)
}

Output:
true
true

func OrderBy ¶

func OrderBy(allowed map[string]string, sort, direction string) func(*gorm.DB) *gorm.DB

OrderBy returns a GORM scope that orders by an allow-listed column.

Example ¶

ExampleOrderBy shows how to apply an allow-listed column sort as a GORM scope.

package main

import (
	"context"
	"fmt"

	libgorm "github.com/phcp-tech/common-library-golang/dbgorm"
	"github.com/phcp-tech/common-library-golang/dbgorm/sqlite"

	"gorm.io/gorm"
)

// exProduct is a minimal GORM model used by the example functions.
type exProduct struct {
	ID       uint `gorm:"primaryKey"`
	Name     string
	Category string
}

// exDB opens a private in-memory SQLite database and migrates exProduct.
// Each call returns an independent database — no shared state between examples.
func exDB() *gorm.DB {
	db, err := sqlite.NewSQLite(&sqlite.Config{Path: ":memory:"})
	if err != nil {
		panic("exDB: " + err.Error())
	}
	if err := db.AutoMigrate(&exProduct{}); err != nil {
		panic("exDB migrate: " + err.Error())
	}
	return db
}

func main() {
	ctx := context.Background()
	db := exDB()
	db.Create(&exProduct{Name: "zebra"})
	db.Create(&exProduct{Name: "apple"})
	db.Create(&exProduct{Name: "mango"})

	allowed := map[string]string{"name": "name"}
	var results []exProduct
	db.WithContext(ctx).Scopes(libgorm.OrderBy(allowed, "name", "ASC")).Find(&results)
	fmt.Println(results[0].Name)
	fmt.Println(results[2].Name)
}

Output:
apple
zebra

func PageSql ¶

func PageSql(para *dto.PageParameter) string

PageSql builds a LIMIT/OFFSET SQL clause from the pagination fields in para. When Limit is -1, all records are returned without a LIMIT clause. Defaults to page 1 and defaultPageLimit when values are unset or invalid; caps Limit at maxPageLimit and Page at maxPage.

Page and Limit are ints, not strings, so — unlike Sort — they carry no SQL injection risk: strconv.Itoa on an int can only ever produce a plain decimal digit string. The Page cap here is a resource-usage guard instead, not a security fix: without it, an arbitrarily large Page still produces a syntactically valid but enormous OFFSET that the database must count past before returning zero rows.

func Paginate ¶

func Paginate(page, limit int) func(*gorm.DB) *gorm.DB

Paginate returns a GORM scope that applies limit and offset pagination. Caps limit at maxPageLimit and page at maxPage — see PageSql's doc comment for why an unbounded page is a resource-usage guard, not a security fix.

Example ¶

ExamplePaginate shows how to apply limit/offset pagination as a GORM scope.

package main

import (
	"context"
	"fmt"

	libgorm "github.com/phcp-tech/common-library-golang/dbgorm"
	"github.com/phcp-tech/common-library-golang/dbgorm/sqlite"

	"gorm.io/gorm"
)

// exProduct is a minimal GORM model used by the example functions.
type exProduct struct {
	ID       uint `gorm:"primaryKey"`
	Name     string
	Category string
}

// exDB opens a private in-memory SQLite database and migrates exProduct.
// Each call returns an independent database — no shared state between examples.
func exDB() *gorm.DB {
	db, err := sqlite.NewSQLite(&sqlite.Config{Path: ":memory:"})
	if err != nil {
		panic("exDB: " + err.Error())
	}
	if err := db.AutoMigrate(&exProduct{}); err != nil {
		panic("exDB migrate: " + err.Error())
	}
	return db
}

func main() {
	ctx := context.Background()
	db := exDB()
	for i := range 5 {
		db.Create(&exProduct{Name: fmt.Sprintf("item-%d", i)})
	}

	var page []exProduct
	db.WithContext(ctx).Scopes(libgorm.Paginate(1, 3)).Find(&page)
	fmt.Println(len(page)) // page 1, limit 3
}

Output:
3

func ScanRaw ¶

func ScanRaw(ctx context.Context, db *gorm.DB, dest any, sql string, args ...any) error

ScanRaw executes a raw SQL query and scans the result into dest.

Example ¶

ExampleScanRaw shows how to scan a scalar result (e.g. COUNT) from a raw query.

package main

import (
	"context"
	"fmt"

	libgorm "github.com/phcp-tech/common-library-golang/dbgorm"
	"github.com/phcp-tech/common-library-golang/dbgorm/sqlite"

	"gorm.io/gorm"
)

// exProduct is a minimal GORM model used by the example functions.
type exProduct struct {
	ID       uint `gorm:"primaryKey"`
	Name     string
	Category string
}

// exDB opens a private in-memory SQLite database and migrates exProduct.
// Each call returns an independent database — no shared state between examples.
func exDB() *gorm.DB {
	db, err := sqlite.NewSQLite(&sqlite.Config{Path: ":memory:"})
	if err != nil {
		panic("exDB: " + err.Error())
	}
	if err := db.AutoMigrate(&exProduct{}); err != nil {
		panic("exDB migrate: " + err.Error())
	}
	return db
}

func main() {
	ctx := context.Background()
	db := exDB()
	db.Create(&exProduct{Name: "pin", Category: "fasteners"})
	db.Create(&exProduct{Name: "clip", Category: "fasteners"})

	var total int64
	err := libgorm.ScanRaw(ctx, db, &total,
		"SELECT COUNT(*) FROM ex_products WHERE category = ?", "fasteners")
	fmt.Println(err == nil)
	fmt.Println(total)
}

Output:
true
2

Example (MultipleRows) ¶

ExampleScanRaw_multipleRows shows how to scan all matching rows into a slice. Pass a pointer to a slice as dest to collect every returned row.

package main

import (
	"context"
	"fmt"

	libgorm "github.com/phcp-tech/common-library-golang/dbgorm"
	"github.com/phcp-tech/common-library-golang/dbgorm/sqlite"

	"gorm.io/gorm"
)

// exProduct is a minimal GORM model used by the example functions.
type exProduct struct {
	ID       uint `gorm:"primaryKey"`
	Name     string
	Category string
}

// exDB opens a private in-memory SQLite database and migrates exProduct.
// Each call returns an independent database — no shared state between examples.
func exDB() *gorm.DB {
	db, err := sqlite.NewSQLite(&sqlite.Config{Path: ":memory:"})
	if err != nil {
		panic("exDB: " + err.Error())
	}
	if err := db.AutoMigrate(&exProduct{}); err != nil {
		panic("exDB migrate: " + err.Error())
	}
	return db
}

func main() {
	ctx := context.Background()
	db := exDB()
	db.Create(&exProduct{Name: "nail", Category: "fasteners"})
	db.Create(&exProduct{Name: "bolt", Category: "fasteners"})
	db.Create(&exProduct{Name: "screw", Category: "fasteners"})

	var products []exProduct
	err := libgorm.ScanRaw(ctx, db, &products,
		"SELECT * FROM ex_products WHERE category = ? ORDER BY name", "fasteners")
	fmt.Println(err == nil)
	fmt.Println(len(products))
	fmt.Println(products[0].Name)
}

Output:
true
3
bolt

Example (SingleRow) ¶

ExampleScanRaw_singleRow shows how to scan the first matching row into a struct. Only the first row is populated; additional rows are discarded.

package main

import (
	"context"
	"fmt"

	libgorm "github.com/phcp-tech/common-library-golang/dbgorm"
	"github.com/phcp-tech/common-library-golang/dbgorm/sqlite"

	"gorm.io/gorm"
)

// exProduct is a minimal GORM model used by the example functions.
type exProduct struct {
	ID       uint `gorm:"primaryKey"`
	Name     string
	Category string
}

// exDB opens a private in-memory SQLite database and migrates exProduct.
// Each call returns an independent database — no shared state between examples.
func exDB() *gorm.DB {
	db, err := sqlite.NewSQLite(&sqlite.Config{Path: ":memory:"})
	if err != nil {
		panic("exDB: " + err.Error())
	}
	if err := db.AutoMigrate(&exProduct{}); err != nil {
		panic("exDB migrate: " + err.Error())
	}
	return db
}

func main() {
	ctx := context.Background()
	db := exDB()
	db.Create(&exProduct{Name: "hammer", Category: "tools"})

	var p exProduct
	err := libgorm.ScanRaw(ctx, db, &p,
		"SELECT * FROM ex_products WHERE name = ?", "hammer")
	fmt.Println(err == nil)
	fmt.Println(p.Name)
}

Output:
true
hammer

func SetDefault ¶

func SetDefault(db *gorm.DB)

SetDefault replaces the process-wide default GORM database instance.

Example ¶

ExampleSetDefault shows how to store a *gorm.DB as the process-wide default. Call SetDefault once at application startup after opening the database.

package main

import (
	"fmt"

	libgorm "github.com/phcp-tech/common-library-golang/dbgorm"
	"github.com/phcp-tech/common-library-golang/dbgorm/sqlite"

	"gorm.io/gorm"
)

// exProduct is a minimal GORM model used by the example functions.
type exProduct struct {
	ID       uint `gorm:"primaryKey"`
	Name     string
	Category string
}

// exDB opens a private in-memory SQLite database and migrates exProduct.
// Each call returns an independent database — no shared state between examples.
func exDB() *gorm.DB {
	db, err := sqlite.NewSQLite(&sqlite.Config{Path: ":memory:"})
	if err != nil {
		panic("exDB: " + err.Error())
	}
	if err := db.AutoMigrate(&exProduct{}); err != nil {
		panic("exDB migrate: " + err.Error())
	}
	return db
}

func main() {
	prev := libgorm.Default()
	defer libgorm.SetDefault(prev) // restore after example

	libgorm.SetDefault(exDB())
	fmt.Println(libgorm.Default() != nil)
}

Output:
true

func SortSql ¶

func SortSql(para *dto.PageParameter) string

SortSql builds an ORDER BY SQL clause from the sort fields in para. Defaults to ordering by "id ASC" when Sort is empty or unsafe.

SortSql only ever produces a plain "ORDER BY <column> <direction>" clause — it deliberately has no locale/charset-aware sorting, since that requires a database-specific SQL function (e.g. PostgreSQL's convert_to, MySQL's CONVERT(... USING ...)) that this dialect-agnostic root package cannot pick correctly on its own. For approximate pinyin ordering of Chinese text, see the dedicated ChineseSortSql in the relevant dialect package (dbgorm/postgres, dbgorm/mysql) instead.

func UpdateByID ¶ added in v0.1.22

func UpdateByID[T any](ctx context.Context, db *gorm.DB, id any, values any) error

UpdateByID updates columns of the record of type T matching the primary key id. values may be a struct (only non-zero fields are updated) or a map[string]any (all specified keys are updated regardless of zero value). Returns gorm.ErrRecordNotFound when no row is matched.

Example ¶

ExampleUpdateByID shows how to update specific columns of a record by primary key. Pass a struct to update only non-zero fields, or a map[string]any to update all specified keys regardless of zero value.

package main

import (
	"context"
	"fmt"

	libgorm "github.com/phcp-tech/common-library-golang/dbgorm"
	"github.com/phcp-tech/common-library-golang/dbgorm/sqlite"

	"gorm.io/gorm"
)

// exProduct is a minimal GORM model used by the example functions.
type exProduct struct {
	ID       uint `gorm:"primaryKey"`
	Name     string
	Category string
}

// exDB opens a private in-memory SQLite database and migrates exProduct.
// Each call returns an independent database — no shared state between examples.
func exDB() *gorm.DB {
	db, err := sqlite.NewSQLite(&sqlite.Config{Path: ":memory:"})
	if err != nil {
		panic("exDB: " + err.Error())
	}
	if err := db.AutoMigrate(&exProduct{}); err != nil {
		panic("exDB migrate: " + err.Error())
	}
	return db
}

func main() {
	ctx := context.Background()
	db := exDB()
	p := &exProduct{Name: "wrench", Category: "tools"}
	db.Create(p)

	// Update a single field using a map to avoid zero-value filtering.
	err := libgorm.UpdateByID[exProduct](ctx, db, p.ID, map[string]any{"category": "hardware"})
	fmt.Println(err == nil)

	// Verify the update.
	updated, _ := libgorm.FirstByID[exProduct](ctx, db, p.ID)
	fmt.Println(updated.Category)

	// Returns ErrRecordNotFound when no row matches.
	fmt.Println(libgorm.IsNotFound(libgorm.UpdateByID[exProduct](ctx, db, 9999, map[string]any{"name": "x"})))
}

Output:
true
hardware
true

Example (Struct) ¶

ExampleUpdateByID_struct shows how to update using a struct value. Only non-zero fields are written — zero values (empty string, 0, false, …) are silently skipped. Use a map[string]any when zero values must be persisted.

package main

import (
	"context"
	"fmt"

	libgorm "github.com/phcp-tech/common-library-golang/dbgorm"
	"github.com/phcp-tech/common-library-golang/dbgorm/sqlite"

	"gorm.io/gorm"
)

// exProduct is a minimal GORM model used by the example functions.
type exProduct struct {
	ID       uint `gorm:"primaryKey"`
	Name     string
	Category string
}

// exDB opens a private in-memory SQLite database and migrates exProduct.
// Each call returns an independent database — no shared state between examples.
func exDB() *gorm.DB {
	db, err := sqlite.NewSQLite(&sqlite.Config{Path: ":memory:"})
	if err != nil {
		panic("exDB: " + err.Error())
	}
	if err := db.AutoMigrate(&exProduct{}); err != nil {
		panic("exDB migrate: " + err.Error())
	}
	return db
}

func main() {
	ctx := context.Background()
	db := exDB()
	p := &exProduct{Name: "hammer", Category: "tools"}
	db.Create(p)

	// Only Category is non-zero, so only that column is updated.
	err := libgorm.UpdateByID[exProduct](ctx, db, p.ID, exProduct{Category: "hand-tools"})
	fmt.Println(err == nil)

	updated, _ := libgorm.FirstByID[exProduct](ctx, db, p.ID)
	fmt.Println(updated.Name)     // unchanged — Name was zero in the struct
	fmt.Println(updated.Category) // updated
}

Output:
true
hammer
hand-tools

func UpdateWhere ¶ added in v0.1.23

func UpdateWhere(ctx context.Context, db *gorm.DB, model any, values any, query any, args ...any) error

UpdateWhere updates columns of all records for model matching query and args. values may be a struct (only non-zero fields are updated) or a map[string]any (all specified keys are updated regardless of zero value). Zero affected rows is treated as success, consistent with DeleteWhere.

Example ¶

ExampleUpdateWhere shows how to update all records matching a condition. Zero affected rows is treated as success, consistent with DeleteWhere.

package main

import (
	"context"
	"fmt"

	libgorm "github.com/phcp-tech/common-library-golang/dbgorm"
	"github.com/phcp-tech/common-library-golang/dbgorm/sqlite"

	"gorm.io/gorm"
)

// exProduct is a minimal GORM model used by the example functions.
type exProduct struct {
	ID       uint `gorm:"primaryKey"`
	Name     string
	Category string
}

// exDB opens a private in-memory SQLite database and migrates exProduct.
// Each call returns an independent database — no shared state between examples.
func exDB() *gorm.DB {
	db, err := sqlite.NewSQLite(&sqlite.Config{Path: ":memory:"})
	if err != nil {
		panic("exDB: " + err.Error())
	}
	if err := db.AutoMigrate(&exProduct{}); err != nil {
		panic("exDB migrate: " + err.Error())
	}
	return db
}

func main() {
	ctx := context.Background()
	db := exDB()
	db.Create(&exProduct{Name: "nail", Category: "fasteners"})
	db.Create(&exProduct{Name: "bolt", Category: "fasteners"})
	db.Create(&exProduct{Name: "brush", Category: "painting"})

	// Promote all fasteners to the "hardware" category.
	err := libgorm.UpdateWhere(ctx, db, &exProduct{}, map[string]any{"category": "hardware"}, "category = ?", "fasteners")
	fmt.Println(err == nil)

	var count int64
	db.Model(&exProduct{}).Where("category = ?", "hardware").Count(&count)
	fmt.Println(count) // nail + bolt
}

Output:
true
2

Example (Struct) ¶

ExampleUpdateWhere_struct shows how to pass a struct as values. Only non-zero fields in the struct are written to the database.

package main

import (
	"context"
	"fmt"

	libgorm "github.com/phcp-tech/common-library-golang/dbgorm"
	"github.com/phcp-tech/common-library-golang/dbgorm/sqlite"

	"gorm.io/gorm"
)

// exProduct is a minimal GORM model used by the example functions.
type exProduct struct {
	ID       uint `gorm:"primaryKey"`
	Name     string
	Category string
}

// exDB opens a private in-memory SQLite database and migrates exProduct.
// Each call returns an independent database — no shared state between examples.
func exDB() *gorm.DB {
	db, err := sqlite.NewSQLite(&sqlite.Config{Path: ":memory:"})
	if err != nil {
		panic("exDB: " + err.Error())
	}
	if err := db.AutoMigrate(&exProduct{}); err != nil {
		panic("exDB migrate: " + err.Error())
	}
	return db
}

func main() {
	ctx := context.Background()
	db := exDB()
	db.Create(&exProduct{Name: "saw", Category: "tools"})
	db.Create(&exProduct{Name: "drill", Category: "tools"})

	// Category is the only non-zero field — Name is left unchanged.
	err := libgorm.UpdateWhere(ctx, db, &exProduct{}, exProduct{Category: "power-tools"}, "name = ?", "drill")
	fmt.Println(err == nil)

	updated, _ := libgorm.FirstWhere[exProduct](ctx, db, "name = ?", "drill")
	fmt.Println(updated.Name)
	fmt.Println(updated.Category)
}

Output:
true
drill
power-tools

Types ¶

type GormConfig ¶

type GormConfig struct {
	MaxOpenConns    int
	MaxIdleConns    int
	ConnMaxLifetime int
	ConnMaxIdletime int
	Logger          *slog.Logger
}

GormConfig contains pool settings and logger for a GORM database connection.

Source Files ¶

View all Source files

Directories ¶

Path	Synopsis
clickhouse
component Package component provides GORM ClickHouse lifecycle integration for bootstrap.	Package component provides GORM ClickHouse lifecycle integration for bootstrap.
mysql
component Package component provides GORM MySQL lifecycle integration for bootstrap.	Package component provides GORM MySQL lifecycle integration for bootstrap.
postgres
component Package component provides GORM PostgreSQL lifecycle integration for bootstrap.	Package component provides GORM PostgreSQL lifecycle integration for bootstrap.
sqlite
component Package component provides GORM SQLite lifecycle integration for bootstrap.	Package component provides GORM SQLite lifecycle integration for bootstrap.
vfs Package vfs opens a SQLite database embedded inside a Go binary using modernc.org/sqlite/vfs and Go's embed.FS.	Package vfs opens a SQLite database embedded inside a Go binary using modernc.org/sqlite/vfs and Go's embed.FS.

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

README ¶

dbgorm

Features

Package Layout

Install

Opening a Database

MySQL

PostgreSQL

SQLite

Low-level Open

Default Instance

Logging

Normal GORM Usage

Helper Functions

Find by ID

Find by Condition

Delete by ID

Delete by Condition

Pagination and Sorting

Raw SQL

Error Handling

Configuration Ownership

Testing

Documentation ¶

Index ¶

Examples ¶

Constants ¶

Variables ¶

Functions ¶

func AutoMigrate ¶ added in v0.1.23

func Close ¶

func Create ¶ added in v0.1.23

func Default ¶

func DeleteByID ¶

func DeleteWhere ¶

func ExecRaw ¶

func FirstByID ¶

func FirstWhere ¶

func HealthChecker ¶

func IsNotFound ¶

func IsSafeSQLIdentifierPath ¶ added in v0.1.26

func IsSafeSQLName ¶ added in v0.1.26

func NormalizeSortDirection ¶ added in v0.1.26

func Open ¶

func OrderBy ¶

func PageSql ¶

func Paginate ¶

func ScanRaw ¶

func SetDefault ¶

func SortSql ¶

func UpdateByID ¶ added in v0.1.22

func UpdateWhere ¶ added in v0.1.23

Types ¶

type GormConfig ¶

Source Files ¶

Directories ¶