Go database/sql Tutorial: 39 Practical Lessons from Core to ORMs & Tools

Overview

This tutorial provides a comprehensive, project‑oriented guide to Go's database/sql package. It is published online at https://godb.rpcx.io and the source Markdown lives in the docs/ directory of the accompanying repository.

What the Tutorial Covers

First 24 lessons – database/sql core: basic model, drivers, connection pooling, queries, parameterization, transactions, context, prepared statements, error handling, isolation levels, migrations, testing, and production practices. Each lesson focuses on a single knowledge point.

Next 15 lessons – ecosystem comparison: ORMs (GORM, Bun, XORM), lightweight tools (sqlx, sqlc, Squirrel, scany, pgx), logging/tracing libraries (sqldb‑logger, go‑sql‑proxy), and engineering utilities (golang‑migrate, goose, go‑sqlmock, Vitess). The goal is to clarify what each library solves and what it does not.

Guiding Principles

Context‑first API: Prefer QueryContext, ExecContext, and other Context ‑aware methods so cancellation and timeouts propagate to every database call.

Unified example driver – modernc.org/sqlite: A pure‑Go SQLite driver that requires no cgo and no external service. Running go test ./... executes all examples on any machine.

Explicit dialect differences: Placeholders, auto‑increment keys, isolation levels, boolean and time types are not abstracted by the standard library. The tutorial shows PostgreSQL and MySQL syntax side‑by‑side where they diverge.

Examples as tests: Every code snippet is a _test.go file that spins up an in‑process SQLite database, eliminating external dependencies.

How to Use the Material

Online: Start at https://godb.rpcx.io and read sequentially.

Source: Browse the Markdown files under docs/.

Run examples:

cd examples
go test ./...      # run all knowledge points
go test -v ./...   # see what each example does

Repository Structure

docs/      39 Markdown lessons (one per page)
examples/  Runnable tests for every lesson
sitegen/   Generator that renders docs into a static site
site/      Generated static site (entry: site/index.html)

Full Curriculum

database/sql core (lessons 01–24): basic model, connection pool, queries, transactions, context, isolation levels, migrations, testing, production practices.

ORM frameworks (lessons 25–27): GORM, Bun, XORM – all built on database/sql; core principles still apply.

Lightweight tools & code generation (lessons 28–32): sqlx, sqlc, Squirrel, scany, pgx – each solves one specific problem.

SQL logging & tracing (lessons 33–34): sqldb‑logger, go‑sql‑proxy – transparent driver‑level SQL logging.

Ecosystem & engineering (lessons 35–39): golang‑migrate, goose, SQLite driver selection, go‑sqlmock, Vitess.

The tutorial references and corrects the classic go-database-sql.org material, filling gaps in connection pooling, context usage, error handling, isolation levels, migrations, and testing that are often glossed over or explained incorrectly.

Begin with lesson 01 at https://godb.rpcx.io/01-model.html.