Why I Built a Go SQL Helper

Zero-boilerplate SQL for Go. Define a struct with tags. That's it.

If you write Go and talk to SQL databases, you know the pain. Every CRUD operation requires writing a raw SQL string, carefully mapping columns to struct fields with rows.Scan, manually wrapping writes in Begin/Commit/Rollback, and keeping your schema definitions in sync with your code. It's tedious, error-prone, and the boilerplate never ends.

This is the story of sqlh — a library I built to eliminate all of that, while staying in the "sweet spot" between raw SQL (too much work) and heavy ORMs (too much magic).

The Problem: Go + SQL = Death by a Thousand rows.Scans

Go's database/sql package is excellent. It gives you a solid, portable foundation for talking to any SQL database. But it intentionally leaves the hard work to you.

Here's what a simple CRUD workflow looks like with raw database/sql:

// 1. Create table — raw DDL string
_, err := db.Exec(`CREATE TABLE IF NOT EXISTS user (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT UNIQUE,
    email TEXT,
    age INTEGER
)`)

// 2. Insert — explicit placeholders and args
_, err = db.Exec(
    "INSERT INTO user (name, email, age) VALUES (?, ?, ?)",
    "Alice", "alice@example.com", 30,
)

// 3. Get by ID — QueryRow + manual Scan
var u User
err = db.QueryRow("SELECT id, name, email, age FROM user WHERE id = ?", 1).
    Scan(&u.ID, &u.Name, &u.Email, &u.Age)

// 4. List all — Query + rows.Next + rows.Scan loop
rows, err := db.Query("SELECT id, name, email, age FROM user ORDER BY name ASC")
var users []User
for rows.Next() {
    var u User
    if err := rows.Scan(&u.ID, &u.Name, &u.Email, &u.Age); err != nil {
        log.Fatal(err)
    }
    users = append(users, u)
}
rows.Close()

// 5. Update — raw SQL with placeholders
_, err = db.Exec(
    "UPDATE user SET email = ?, age = ? WHERE id = ?",
    "alice.new@example.com", 31, 1,
)

// 6. Delete — raw SQL
_, err = db.Exec("DELETE FROM user WHERE id = ?", 1)

That is ~115 lines of code for six basic operations. And every time you add a column, you must update the CREATE TABLE string, the INSERT columns, the SELECT columns, and the rows.Scan call. One typo in any of those, and you get a runtime error — no compile-time safety.

The Pain Points

Existing Solutions: sqlx, GORM, and the Missing Middle

The Go ecosystem offers two well-known paths to reduce this pain. Both have trade-offs.

sqlx: Better, But Still Manual

sqlx is a popular enhancement over database/sql. It adds StructScan, Get, Select, and named query parameters. You still write raw SQL, but rows.Scan is automated.

// sqlx: still manual SQL, but StructScan eliminates Scan
var u User
dbx.Get(&u, "SELECT id, name, email, age FROM user WHERE id = ?", 1)

sqlx saves about 30% of the boilerplate (down to ~80 lines). But you still write every CREATE TABLE, INSERT, SELECT, UPDATE, and DELETE by hand. SQL generation is not its job.

GORM: Full ORM, Full Magic

GORM is the heavyweight champion. It generates everything — schema, queries, migrations — and provides a rich chainable API. But it comes with a cost:

• Heavy reflection overhead at runtime
• Steep learning curve — tags, hooks, scopes, associations
• ~4 MB binary size increase just for the ORM
• Magic that hides complexity — until it doesn't, and you spend hours debugging

For large teams with dedicated DBAs and complex domain models, GORM is a solid choice. For CLI tools, startups, and small-to-medium services, it's overkill.

sqlh: The Sweet Spot

sqlh lives between sqlx and GORM:

• Zero-boilerplate CRUD — struct tags generate all SQL
• Type-safe via Go generics — Get[User]() returns *User, not interface{}
• No magic — what you see in the struct is what you get in the database
• Lightweight — minimal reflection, cached metadata, no hidden complexity

How sqlh Works: Struct Tags as Single Source of Truth

The core idea is simple: your Go struct is your schema.

type User struct {
    ID    int64  `db:"id" db_key:"not null primary key autoincrement"`
    Name  string `db:"name" db_key:"unique"`
    Email string `db:"email"`
    Age   int    `db:"age"`
}

Three struct tags control everything:

From this single struct definition, sqlh generates:

• CREATE TABLE — sqlh.Create[User](db) generates and executes CREATE TABLE IF NOT EXISTS user (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT UNIQUE, email TEXT, age INTEGER)
• INSERT — sqlh.Insert(db, User{Name: "Alice"}) generates INSERT INTO user (name, email, age) VALUES (?, ?, ?)
• SELECT — sqlh.Get[User](db, ...) generates SELECT id, name, email, age FROM user WHERE ... LIMIT 2
• UPDATE — sqlh.Update(db, ...) generates UPDATE user SET name=?, email=?, age=? WHERE ...
• DELETE — sqlh.Delete[User](db, ...) generates DELETE FROM user WHERE ...

Architecture

┌─────────────────────────────────────────────┐
│  sqlh package                               │
│  Insert, Get, List, Update, Delete, Set,    │
│  Create — with auto-transactions            │
├─────────────────────────────────────────────┤
│  query package                              │
│  SQL generation, metadata cache, JOINs      │
├─────────────────────────────────────────────┤
│  database/sql (stdlib)                      │
│  Connection pool, raw query execution       │
└─────────────────────────────────────────────┘

Key Design Decisions

1. Generics-first (Go 1.25+) — Get[User]() returns *User with compile-time type safety. No interface{}, no type assertions.
2. Reflection at call-time — Struct metadata is parsed once and cached in a sync.Map keyed by reflect.Type. Subsequent calls reuse table names, field lists, and scan metadata.
3. Auto-transactions on writes — Every Insert, Update, Delete, and Set is automatically wrapped in BEGIN...COMMIT with ROLLBACK on error. You never forget a transaction again.
4. Database lock retry — SQLite "database is locked" errors are automatically retried up to 20 times with 100ms backoff. Production-grade resilience out of the box.
5. Multi-database support — SQLite (primary), MySQL, PostgreSQL (both CI-tested), and SQL Server (experimental).

CRUD in 50 Lines: The Quick Start

Here's the complete CRUD workflow with sqlh. Same operations as the raw SQL example above — ~57% less code:

package main

import (
    "database/sql"
    "fmt"

    "github.com/kirill-scherba/sqlh"
    _ "github.com/mattn/go-sqlite3"
)

type User struct {
    ID    int64  `db:"id" db_key:"not null primary key autoincrement"`
    Name  string `db:"name" db_key:"unique"`
    Email string `db:"email"`
    Age   int    `db:"age"`
}

func main() {
    db, _ := sql.Open("sqlite3", "file::memory:?cache=shared")
    defer db.Close()

    // 1. Create table from struct
    sqlh.Create[User](db)

    // 2. Insert
    sqlh.Insert(db, User{Name: "Alice", Email: "alice@example.com", Age: 30})
    bobID, _ := sqlh.InsertId(db, User{Name: "Bob", Email: "bob@example.com", Age: 25})

    // 3. Get by ID — returns *User, not interface{}
    u, _ := sqlh.Get[User](db, sqlh.Eq("id", bobID))
    fmt.Println(u.Name) // "Bob"

    // 4. List all — returns []User + next offset
    users, _, _ := sqlh.List[User](db, 0, "", "name ASC")
    fmt.Println(len(users)) // 2

    // 5. Update — pass full struct to avoid zeroing other columns
    sqlh.Update(db, sqlh.UpdateAttr[User]{
        Row:    User{Name: "Alice", Email: "alice.new@example.com", Age: 31},
        Wheres: []sqlh.Where{sqlh.Eq("id", 1)},
    })

    // 6. Delete
    sqlh.Delete[User](db, sqlh.Eq("id", bobID))
}

~50 lines. No raw SQL. No rows.Scan. No transaction management. No column ordering errors.

Side-by-Side Comparison

Benchmarks: The Numbers

How fast is sqlh in practice? I created a standalone bench/ module comparing raw database/sql, sqlx, GORM, and sqlh on the same CRUD workload. All benchmarks use in-memory SQLite — zero external setup.

Reproduce on your machine:

cd bench && go test -bench=. -benchmem -benchtime=1s

CRUD Throughput (ops/sec)

Memory Allocations (bytes/op, allocs/op)

What the Numbers Tell Us

• GORM has the highest latency and allocation footprint across all operations, reflecting its rich feature set and internal reflection overhead.
• sqlh sits between raw sql/sqlx and GORM. The moderate overhead comes from auto-generated SQL, struct tag parsing, and built-in transaction wrapping for writes.
• sqlh trades raw speed for correctness: every write is auto-transacted with rollback on error, eliminating an entire class of bugs at the cost of ~2–6x latency versus raw sql for single-row mutations.
• ListAll is dominated by the cost of scanning 100 rows. All libraries show similar performance here.

Environment: Linux AMD Ryzen 9 3900, Go 1.26.3, SQLite in-memory.
Run cd bench && go test -bench=. -benchmem -benchtime=1s on your own hardware for an apples-to-apples comparison.

When to Use sqlh

sqlh is not a silver bullet. Here's where it shines and where you might want something else:

Getting Started

go get github.com/kirill-scherba/sqlh

• 📖 README & Quick Start
• 📦 pkg.go.dev reference
• 🏗️ Source code

What’s Next

sqlh is actively developed. As of v0.8.0 (June 2026), the library supports:

• ✅ Full CRUD with auto-transactions
• ✅ Native UPSERT (PostgreSQL, SQLite, MySQL)
• ✅ JOIN queries with composite struct scanning
• ✅ Go 1.25 iterators (ListRange) for lazy streaming
• ✅ Type-safe WHERE helpers (Eq, Ne, Gt, Like, In, etc.)
• ✅ Database lock retry for SQLite
• ✅ Multi-database support (SQLite, MySQL, PostgreSQL)

On the roadmap: aggregate functions (SUM, AVG), schema migrations, batch operations, and transactional reads. The API is stabilizing toward v1.0.0.

If you’re building a Go project that talks to SQL and you’re tired of writing the same boilerplate over and over — give sqlh a try. Define your struct. That’s it.

Written by Kirill Scherba. sqlh is open source under the BSD license. Contributions welcome.