sqlkit

go-sqlkit

Type-safe SQL control layer for Go 1.25+. Generic Table[T], composable expression builder, explicit JOINs with FK auto-join, composite indexes, and safe-by-default migrations — for mysql, sqlite, and postgres.

No interface{}/reflect in return types. Full parameterization through a shared expr.Writer (continuous placeholder counter). Savepoint-based nested transactions. ~10% overhead vs hand-written db.Query + Scan.

Quick Start

package main

import (
    "context"
    "log"

    sqlkit "github.com/GlshchnkLx/go-sqlkit"
    _ "modernc.org/sqlite"
)

type User struct {
    ID   int64  `sql:"id,pk,autoincr"`
    Name string `sql:"name"`
    Age  int    `sql:"age"`
}

func main() {
    db, err := sqlkit.Open("sqlite", ":memory:", "sqlite")
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()
    ctx := context.Background()

    users, _ := sqlkit.Register[User](db, sqlkit.WithTableName("users"))

    create, _ := sqlkit.NewCreate[User](sqlkit.WithTableName("users"))
    db.Exec(ctx, create.WithIfNotExists())

    ins, _ := sqlkit.NewInsert[User](sqlkit.WithTableName("users"))
    db.Exec(ctx, ins.Rows(&User{Name: "Alice", Age: 30}))

    got, _ := sqlkit.Query[User](db).OrderBy(users.Field("id")).First(ctx)
    log.Printf("user: %+v", got)
}

Installation

go get github.com/GlshchnkLx/go-sqlkit

Import drivers for side effects:

import (
    _ "github.com/go-sql-driver/mysql"  // mysql
    _ "github.com/lib/pq"               // postgres
    _ "modernc.org/sqlite"              // sqlite (pure Go, no cgo)
)

Features

sql struct tags — define table metadata inline:

type Membership struct {
    TenantID int64  `sql:"tenant_id,pk,index=by_tenant_role"`
    UserID   int64  `sql:"user_id,pk,index=by_tenant_role"`
    Role     string `sql:"role"`
}

Tags support: pk, autoincr, notnull, unique/unique=group, index/index=group, type=, default=, check=, fk=table.col, name=, old>new (rename detection).

Table options: WithTableName, WithPrimaryKey, WithIndex, WithIndexMethod, WithUnique, WithIndexPrefix, WithUniquePrefix.

Database options: WithDatabaseIndexPrefix, WithDatabaseUniquePrefix, WithDatabaseScanCacheSize.

Expression builder — composable WHERE/SET predicates:

sqlkit.Query[User](db).
    Where(expr.And(
        expr.Gt(users.Field("age"), 18),
        expr.Or(
            expr.Like(users.Field("name"), "A%"),
            expr.Eq(users.Field("role"), "admin"),
        ),
    )).
    All(ctx)

Includes Eq/Ne/Gt/Lt/Ge/Le, Like/NotLike, In/NotIn, Between, IsNull, Regexp, And/Or/Not, Match (&struct → AND equalities), RawExpr, subqueries (Exists/Any/All/Subquery).

Typed DML/DDL builders:

Auto-join — embed registered structs, auto-resolve FK JOINs:

type UserWithProfile struct {
    User
    Profile
}
rows, _ := sqlkit.Query[UserWithProfile](db).FromAuto().All(ctx)

Many-to-many via Through:

sqlkit.Query[PostWithTags](db).
    FromAuto().
    Through("post_tags", "post_id", "tag_id").
    All(ctx)

Safe-by-default migrations — auto-diff applies safe changes (add table, add nullable column, add/drop index/unique) and refuses risky ones (drop, type change, PK change) — those require a file migration:

db.RegisterMigration(migrate.File{
    Version: 1,
    Up:   func(ctx context.Context, tx *sql.Tx) error { /* ... */ },
    Down: func(ctx context.Context, tx *sql.Tx) error { /* ... */ },
})
res, err := db.Migrate(ctx) // files + auto-diff in one transaction

Nested transactions via savepoints:

tx, _ := db.Begin(ctx)
nested, _ := tx.Begin(ctx) // SAVEPOINT
nested.Rollback(ctx)       // ROLLBACK TO SAVEPOINT — outer survives
tx.Commit(ctx)

Dialects:

Custom type mapping: dialect.RegisterCustomType(reflect.TypeFor[MyUUID](), "UUID")

Cached scan plan — LRU cache keyed by (T, columns), typed buffers, no reflection per row.

Errors

Sentinel errors checked via errors.Is:

Typed errors via errors.As: *ErrTableInvalidError (Field/Opt/Reason/Cause), *ErrMigrationRequiresFile (Change/Hint).

Examples

Run with go run -tags examples ./examples/<name>:

Testing

go test ./...           # in-memory SQLite
go test -race ./...     # with race detector
go test -cover ./...    # coverage report
go vet ./...            # static analysis
go test -bench=. ./...  # benchmarks

MySQL/Postgres via env vars: SQLKIT_TEST_MYSQL_DSN=... / SQLKIT_TEST_POSTGRES_DSN=...

Coverage by package: sqlkit 92.8%, dialect 81.6%, table 90.2%, query 45.0%, expr 46.8%, migrate 51.4%.

Documentation

Detailed docs in docs/: architecture, testing, error handling, file migrations, dialect/expr/migrate packages, mental map.

License

Apache License 2.0 — see LICENSE.