go-database

Go Database

Go's database/sql is a thin, driver-pluggable foundation. Most projects layer one of sqlx, sqlc, or pgx on top for ergonomics. ORMs (GORM, ent) trade SQL visibility for one less line of code — a bad trade in production.

Core Rules

1. SQL is the source of truth. It is reviewed, version-controlled, and explained in code. Magic ORM queries are the opposite.
2. Always parameterize. $1/? placeholders, never string concatenation. The driver handles escaping; you cannot.
3. Every I/O call takes ctx. QueryContext, ExecContext, GetContext. No context = no timeout = a stuck handler.
4. Distinguish "not found" from "error". errors.Is(err, sql.ErrNoRows) is a domain signal, not a failure.
5. Close rows. defer rows.Close() immediately after QueryContext. Forgetting it leaks a pool connection.
6. Configure the pool. Default MaxOpenConns is unlimited — a runaway request rate exhausts the DB.

Library Decision

Library	Best for	Struct scanning	Code-gen
database/sql	Minimal deps, multi-driver portability	Manual Scan	No
sqlx	Sweetens database/sql ergonomics	StructScan, Get, Select	No
sqlc	Type-safe queries derived from .sql files	Generated structs and funcs	Yes
pgx (v5)	PostgreSQL-only, 30-50% faster, native types	pgx.RowToStructByName	No
GORM / ent	Avoid in new code	Reflection	Yes

Why not ORMs.

• Generated queries are unpredictable; N+1 problems are invisible at the call site.
• Hooks (BeforeCreate, AfterUpdate) create implicit state machines.
• Schema migrations entangle with application code.
• Learning the ORM API is harder than learning SQL, and the abstraction leaks at every interesting query.

Read references/library-tradeoffs.md when picking between sqlx, sqlc, and pgx for a new project.

Parameterized Queries

// VERY BAD — SQL injection.
q := fmt.Sprintf("SELECT * FROM users WHERE email = '%s'", email)

// Good — placeholder, driver-escaped.
err := db.GetContext(ctx, &u, "SELECT id, email FROM users WHERE email = $1", email)