How to read this book

This book builds one project, from an empty folder to a deployable, money-taking service: a task manager API called taskd. Every chapter changes the same codebase, in order. Nothing is hand-waved with “assume you have X” — if the code needs something, we build it or install it on the page where it first matters.

This is the beginner edition. The system it builds is not a beginner system: it is the real thing, with connection pools, graceful shutdown, metrics, rate limits, background workers, Stripe billing and a CI pipeline. We did not simplify the software. We simplified the explanation — every idea gets introduced from first principles, at the moment you need it, in plain words.

Who this book is for

You, if:

• you have never programmed, or you have written a bit of Python or JavaScript and never shipped anything;
• you have never written Go;
• you are willing to type things out, read error messages, and be temporarily confused.

You do not need to know Go, SQL, HTTP, Docker, or what a “connection pool” is. Four short warm-up chapters teach each of those before the code needs them:

If you already know some of that, skim it. The rest of the book assumes you have read them.

What you’ll have at the end

A single Go program, about 4,000 lines, that:

• serves a JSON API for tasks — create, read, update, delete, search, sort, paginate;
• registers users, stores passwords safely, and authenticates requests with tokens;
• sells three plans (Free, Pro, Business) through Stripe, and enforces what each plan can do;
• caches hot reads, rate-limits abusers, sends email in the background;
• reports its own health and speed to Prometheus, and logs in a format machines can search;
• ships as a 15 MB Docker image with a pipeline that refuses to deploy broken code.

And a folder of notes in learnings/ that proves you understood it, written by you.

How each chapter is built

Every chapter follows the same shape. Once you have read two of them you will know exactly where to look for what you need.

The original edition of this book had four of those sections. The other nine exist because a first-timer needs them, and because you learn a thing properly when you can predict it, break it, and explain it — not when you have merely copied it.

The two people this book learned from

The codebase has two influences, and it is worth naming them so you know which instincts to copy.

Alex Edwards (author of Let’s Go Further) gives us the structure: the cmd/api + internal folder layout, the application struct that carries shared dependencies, helper functions for JSON, an explicit errors.go, a hand-rolled validator package, stateful token authentication, optimistic concurrency with a version column, graceful shutdown done correctly, and a Makefile-driven workflow. If you have read his books, this codebase will feel like home. If you haven’t, buy them — this book is a complement, not a substitute.

Kailash Nadh (CTO of Zerodha, India’s largest stockbroker; author of listmonk, koanf and stuffbin) gives us the temperament: boring technology, brutally few dependencies, plain SQL you can read, a single static binary, configuration in one TOML file with environment-variable overrides (we use his koanf library for exactly that), and a deep suspicion of frameworks, ORMs, dependency-injection containers and microservices you don’t need. His teams run systems serving millions of users on a handful of ordinary servers. We build like that.

Where the two philosophies disagree — Edwards wraps database access in model structs, Nadh calls SQL functions straight from handlers — the book stops and argues it out in front of you, then picks a side. That argument is the education.

What you need installed

Go 1.24 or newer, Docker with Compose, and curl. That is genuinely all — Postgres, DragonflyDB, the migration tool, the mail server and everything else arrive through Docker as we go. The next chapter installs each one and proves it works.

Versions pinned in this book (newer patch versions are fine):

Following along without getting lost

Every time a chapter creates a new function or dependency, it also shows the wiring — the exact change to main.go or routes.go that puts it to work. Those small blocks are the connective tissue; never skip them.

Three safety nets, for when you fall out of sync:

1. Checkpoints. Every chapter ends with a command and the exact output it should print. If your output differs, stop there — do not continue and hope.
2. Appendix A has the final file tree and Appendix E the complete, annotated main.go. Compare yours against them and you will find the missing wire in a minute.
3. Appendix H is a troubleshooting index: error message on the left, cause and fix on the right, for every error this book can produce. Appendix F holds the complete final routes.go — the whole API on one screen — and the full OpenAPI spec.

How to use the learnings/ folder

There is a learnings/ folder next to the book with one worksheet per chapter. The rhythm that works:

1. Read the chapter once, all the way through, without typing anything. You are just meeting the ideas.
2. Read it again, typing every code block and running every checkpoint.
3. Close the book. Open learnings/chNN.md and fill it in from memory — in your own words. Looking something up is fine; copy-pasting the book’s sentences is not.
4. Anything you couldn’t explain goes in the “still don’t understand” list. That list is the most valuable thing you own. Carry it forward; most items resolve themselves two chapters later.

If a worksheet takes you more than twenty minutes, you are copying rather than recalling.

A note on honesty

Everything in this book compiles and runs. You will still make typos, and versions drift. When something breaks, the debugging is the course — it is not an interruption of the learning, it is the learning. Read the error message. It is Go: the error is usually telling the truth.

You will also hit moments where the amount of code for something apparently simple feels absurd. That feeling is correct and temporary. The extra code is almost always one of three things: a timeout, an error path, or a lie you’re refusing to tell your future self. Chapter by chapter, you will start recognising them on sight.

Take it slowly. Two chapters an evening is a good pace. Nobody is timing you.

Before you begin

This is the warm-up. By the end of it you will have a terminal you are not afraid of, seven programs installed and proven to work, a folder for your notes, and a Go program you wrote and ran yourself. Nothing here teaches Go the language — Go in one sitting does that. This chapter is about the machine you will be operating for the next 27 chapters.

Time: about 25 minutes reading, 30–60 minutes installing.

Permission to skim: if you already live in a terminal and have Go 1.24+, Docker and an editor working, run the verification block in §5.7, read §8 (How to read this book’s code blocks), and go to Chapter 1 (Introduction).

1. What a terminal is

The terminal is a window where you type a line, press Enter, a program runs, and text comes back. The graphical desktop is a convenience layer on top; the terminal is the layer the tools in this book actually speak.

Where you are

When the shell is ready it prints a prompt (usually ending in $ or %) and waits.

The shell always has a current working directory — one folder it considers “here”. When you type go run ., the . means “this folder”. In the wrong folder you get an error that has nothing to do with your code. More beginner confusion comes from this than from any language feature.

Two special names: .. is the folder above (cd .. goes up), ~ is your home folder.

Commands, arguments, flags

   mkdir      -p          ~/taskd-learnings
   ───┬──     ─┬─         ───────┬─────────
  the program  a flag        an argument
               (changes how     (what to
                it behaves)      act on)

Flags start with - or --. curl -i localhost:4000 runs curl with the -i flag on the argument localhost:4000. Each flag you meet gets explained where it first appears.

Four keys that save you

• Tab completes a name you have started typing. Type cd task, press Tab, the shell finishes it. Treat this as a spell-checker: if Tab does not complete, the thing does not exist, and you have found your bug before running anything.
• Up arrow brings back the previous command. You will run go run ./cmd/api several hundred times in this book. Type it once.
• Ctrl-C stops the program currently running. Chapter 2 starts a server that never returns on its own; Ctrl-C is how you get your prompt back. Chapter 4 (A server that dies well) is entirely about what your program should do on receiving it.
• Ctrl-D means “no more input”. You need it to leave psql in Chapter 5 (PostgreSQL and migrations).

Silence is success

Unix tools print nothing when they succeed. mkdir taskd prints nothing; cd taskd prints nothing. Unexpected text is the alarm, not the absence of it. Underneath, every command also returns an exit code — 0 for success, anything else for failure. You rarely look at it, but Chapter 26 (CI/CD: the robot that says no) is built entirely on it.

Run this now

cd ~
mkdir taskd-warmup
cd taskd-warmup
pwd
ls

pwd should print a path ending in taskd-warmup, and ls should print nothing at all, because the folder is empty. Here is a real transcript of the same three-command shape on another machine, with a folder created and listed from its parent:

/Volumes/ssd-main/Developer/book-golang/build/scratch/demo
taskd-demo

2. Which computer are you on?

Three supported setups, two of which are the same setup.

Open PowerShell as Administrator (right-click Start, “Terminal (Admin)”) and run wsl --install. Restart when asked. On next boot an Ubuntu window opens and asks you to invent a username and password — that is your Linux account, and the password is what sudo will ask for later. Then confirm the version with wsl --list --verbose: the VERSION column must say 2. If it says 1, run wsl --set-version Ubuntu 2.

From then on, “open a terminal” means “open the Ubuntu app”.

Three more WSL2 details:

1. Docker Desktop needs a toggle: Settings → Resources → WSL Integration → enable for Ubuntu. Without it, docker is not found inside your Ubuntu shell.
2. localhost crosses the boundary. A server on port 4000 inside WSL2 opens at http://localhost:4000 in your Windows browser — which matters from Chapter 18 (Prometheus) and Chapter 21 (Background work and transactional email) onward.
3. Turn off line-ending rewriting, once: git config --global core.autocrlf false. Windows line endings inside a Makefile produce the same baffling missing separator error as the tab mistake in §8.

3. What “installing” means

A program is a file. Installing it means putting that file somewhere your shell knows to look, so that typing its name is enough.

The shell does not search your disk. It looks in an ordered list of folders held in an environment variable called PATH.

echo $PATH | tr ':' '\n'

That prints the search list, one folder per line, in order. When a program is not on it, you get the most common installation error there is. Real output, first from zsh and then from bash:

zsh:1: command not found: flurble
bash: flurble: command not found

That message means exactly one thing: the shell looked through every folder in PATH and found nothing by that name. It does not mean the program is broken or that your flags are wrong. To ask where the shell would find something, run command -v go — it prints a full path, or prints nothing and fails.

4. The tools, and why each is here

Installed later, on the page that needs them — do not install these now: migrate (Chapter 5), sqlc (Chapter 7, sqlc: SQL in, type-safe Go out), and the stripe CLI (Chapter 16, Stripe II: webhooks).

5. Installing, one tool at a time

Each subsection ends with the command that proves it worked. Run it before moving on. If a check fails, §6 has the fix.

5.1 An editor: VS Code and the Go extension

Download from https://code.visualstudio.com. On WSL2, install VS Code on Windows and add the WSL extension, so the Windows editor can edit files living inside Linux.

Then press Ctrl+Shift+X (Cmd+Shift+X on Mac), search Go, and install the extension published by the Go Team at Google. The first time you open a .go file it offers to install helper tools. Say yes.

The important one is gopls, the Go language server. It reads your code as you type and gives you red underlines under errors before you run anything, Ctrl-click jump-to-definition into any function including the standard library’s, and formatting on save.

Turn that last one on now: Settings (Ctrl+,), search format on save, tick it.

Open the folder, not the file. VS Code’s Go support works on a folder containing a go.mod. Use File → Open Folder. Open a lone .go file and gopls has no module to reason about, so half its features go quiet.

Check with code --version. On the machine used here that printed 1.133.0 plus a commit hash and an architecture. Any version is fine.

5.2 Git

Git records snapshots of your project, so you can answer “what did I change since it worked?” — the most effective debugging tool you own.

git --version

Real output here:

git version 2.39.5 (Apple Git-154)

Any 2.x is fine.

5.3 Go 1.24 or newer

Do not install Go from your Linux distribution’s package manager. apt install golang gives you a version that is often more than a year old, and this book needs 1.24+.

macOS. First find your chip:

uname -m

arm64 is Apple Silicon; x86_64 is an Intel Mac. Download the matching .pkg from https://go.dev/dl/ — darwin-arm64.pkg or darwin-amd64.pkg — and double-click it. It installs into /usr/local/go and puts /usr/local/go/bin on your PATH.

Ubuntu / WSL2. Unpack the Linux tarball into /usr/local, replacing anything already there. Substitute the current version from go.dev/dl:

curl -LO https://go.dev/dl/go1.24.0.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.24.0.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

(On macOS the startup file is ~/.zshrc, not ~/.bashrc.)

go version

Real output here:

go version go1.25.6 darwin/arm64

Read it left to right: the toolchain version (go1.25.6), then the operating system and processor architecture it was built for (darwin is macOS’s internal name). Yours must say 1.24 or higher; on Ubuntu the suffix reads linux/amd64 or linux/arm64.

The one extra step everyone skips

Two tools later in this book — migrate in Chapter 5 and sqlc in Chapter 7 — are installed by Go itself, with go install. That command puts the finished program in $(go env GOPATH)/bin, usually ~/go/bin. That folder is not on PATH by default.

So you install migrate successfully, run make db/migrations/up, and get migrate: command not found at the exact moment you can least diagnose it. Fix it before it can happen:

echo 'export PATH="$PATH:$(go env GOPATH)/bin"' >> ~/.zshrc
source ~/.zshrc

Use ~/.bashrc on Ubuntu and WSL2. Then prove it:

echo $PATH | tr ':' '\n' | grep go

You should get a line ending in /go/bin. Here that printed /Users/shine/go/bin.

5.4 Docker Desktop, with Compose

Download Docker Desktop from https://www.docker.com/products/docker-desktop/.

• macOS: pick the build matching your uname -m answer. The wrong one is a large download that fails at launch.
• Windows: install it on Windows, not inside Ubuntu, then enable WSL integration (§2).
• Ubuntu, native: Docker Desktop for Linux works, or install Docker Engine plus the Compose plugin from Docker’s repository. Afterwards run sudo usermod -aG docker $USER and log out and back in, or every docker command will demand sudo.

Docker Desktop must be running. It is an application, not only a command. Look for the whale icon in your menu bar or system tray; without it, every docker command fails no matter how correctly it is installed.

docker compose version

Real output here:

Docker Compose version v5.1.0

Note the shape: docker compose, two words with a space. Any tutorial telling you to run docker-compose with a hyphen is written for a retired version. This book only ever writes docker compose.

5.5 curl

macOS ships with it. On Ubuntu and WSL2: sudo apt install curl. Check with curl --version. The first line here was:

curl 8.7.1 (x86_64-apple-darwin24.0) libcurl/8.7.1 (SecureTransport) LibreSSL/3.3.6 zlib/1.2.12 nghttp2/1.63.0

Only the first two words matter. Any 7.x or 8.x is fine.

5.6 make and jq

make reads a file called Makefile — a list of named shortcuts, so make run/api runs whatever long command that name was defined as. Chapter 5 writes the first one; about forty later commands go through it. jq filters and pretty-prints JSON; Chapter 19 (Logging that pays rent) uses it to prove why machine-readable logs are worth the trouble.

Real first lines from make --version and jq --version here:

GNU Make 3.81
jq-1.6-159-apple-gcff5336-dirty

The word GNU is what matters for make. Any jq 1.6 or newer is fine.

5.7 The verification ritual

Run all of it at once. Come back to this block whenever you suspect your machine rather than your code.

go version
git --version
docker compose version
curl --version
make --version
jq --version
code --version

A passing run, from the machine this chapter was written on, trimmed to each command’s first line:

go version go1.25.6 darwin/arm64
git version 2.39.5 (Apple Git-154)
Docker Compose version v5.1.0
curl 8.7.1 (x86_64-apple-darwin24.0) libcurl/8.7.1 ...
GNU Make 3.81
jq-1.6-159-apple-gcff5336-dirty
1.133.0

6. When an install fails

The last two rows are genuine transcripts from GNU Make 3.81. Newer versions quote the filename slightly differently; match on the words missing separator and No rule to make target.

7. Your first 60 seconds of Go

Before Chapter 1 says a word about architecture, run something.

cd ~
mkdir go-practice
cd go-practice
go mod init taskd-practice

Real output from that last command:

go: creating new go.mod: module taskd-practice

Now one file (File → Open Folder → go-practice, then a new file hello.go):

// ~/go-practice/hello.go — new file (scratch practice, not part of taskd)
package main

import "fmt"

func main() {
	fmt.Println("hello from Go")
}

Four things are happening, and every Go file in this book has all four:

1. package main — this file belongs to the package main, the one Go treats as a runnable program rather than a library.
2. import "fmt" — pull in the standard library’s formatting package. Import something you don’t use and Go refuses to compile, deliberately.
3. func main() — where the program starts. Exactly one per program.
4. A tab-indented body. Format-on-save handles that for you.

go run .

Real output:

hello from Go

go run . means “compile everything in this folder and run it now, discarding the result”. The book’s daily command is go run ./cmd/api, the same idea pointed at a subfolder. Chapter 25 (Docker) switches to go build, which keeps the compiled file instead of throwing it away.

8. How to read this book’s code blocks

1. The path comment is an instruction. Every Go, SQL, YAML and Makefile block opens with a comment naming its file and what to do with it:

// cmd/api/main.go — replaces the whole file

That line is not part of the program. It says: create or open cmd/api/main.go, relative to your project root, and replace its contents. Other variants are — new file and — add this function.

2. In a shell block, # lines are output, not commands. The original book prints both together:

go run ./cmd/api
# time=2026-... level=INFO msg="starting server" addr=:4000 env=development

You type line one; line two is what the computer says back. This edition mostly splits them into two blocks so you can copy commands safely, but you will meet the combined form.

3. Never type a leading $. Some books use it to mark the prompt. It is not part of the command.

4. ... means code was left out. A block containing ... or /* params as before */ is a fragment, not a file. Typing ... into a Go file is a syntax error. Where the original elided something you genuinely need, this edition prints the complete version.

5. Placeholders are yours to substitute. Put your own name in github.com/yourname/taskd, consistently, everywhere. $TOKEN and sk_test_... are values you will have generated by the time you need them.

6. Tabs in makefile blocks are load-bearing. GNU make requires every recipe line to begin with one real Tab. Spaces produce this, which names a real line and explains nothing:

Makefile:2: *** missing separator.  Stop.

That transcript is genuine — it is what a four-space indent produces. If you copy a Makefile out of a PDF, retype the indentation.

9. The edit-run-read-the-error loop

   ┌──────────┐      ┌──────────┐      ┌────────────────┐
   │   edit   │ ───▶ │   run    │ ───▶ │ read the error │
   └──────────┘      └──────────┘      └────────────────┘
        ▲                                       │
        └───────────────────────────────────────┘

Beginners treat the third box as failure and stop. It is the compiler answering a question you asked. Here are the three shapes of answer you will get in the first ten chapters, each produced for real.

Shape 1: a compile error that names your mistake

Replace hello.go with this — a miniature of Chapter 2’s main.go, with one deliberate typo.

// ~/go-practice/hello.go — scratch practice; contains a deliberate typo
package main

import (
	"log/slog"
	"os"
)

func main() {
	logger := slog.New(slog.NewTextHandler(os.Stdout, nil))
	logger.Inf("starting server", "addr", ":4000")
}

Run go run .. Real output:

# taskd-practice
./hello.go:10:9: logger.Inf undefined (type *slog.Logger has no field or method Inf)

Every Go compile error has that shape:

File, line, column, type, name. Fix Inf to Info, save, run again:

time=2026-08-16T00:28:40.215+05:30 level=INFO msg="starting server" addr=:4000

That is real slog output, and you will read hundreds of lines like it. Note the shape: key=value pairs, not a sentence.

Shape 2: a syntax error pointing at the wrong line

Now break the structure. Take a working six-line file and delete the final }:

// ~/go-practice/hello.go — scratch practice; final } deliberately deleted
package main

import "fmt"

func main() {
	fmt.Println("hello from Go")

Real output:

# taskd-practice
./hello.go:7:1: syntax error: unexpected EOF, expected }

The file has six lines. The error is at line 7, which does not exist. EOF means end of file: the compiler read to the very end still waiting for a } that never came, and reported where it ran out of file, not where you erred.

For syntax errors, the line number is where the compiler noticed. Start there and read upward, looking for an unclosed brace, bracket or quote. Click a { and gopls highlights its partner.

A related variant, when code follows the missing brace, reads syntax error: unexpected name helper, expected ( and points at a perfectly correct function two lines below the real problem. Same rule, same cure.

Shape 3: not a Go error at all

Fix the file. Now, without starting any server:

curl -i localhost:4000/v1/healthcheck

Real output:

curl: (7) Failed to connect to localhost port 4000 after 1 ms: Couldn't connect to server

Nothing about Go. Nothing about your code. curl knocked on port 4000 and nobody answered, because no program is listening there. (The wording after curl: (7) varies between curl versions; the (7) and the word “connect” are the signal.)

Nine times in ten, the cause is that the server is not running, or that it is running in a terminal tab you forgot about. Both are found by looking at your other terminal windows before touching the code.

When something breaks, the debugging is the course. Read the error. It’s Go — the error is usually telling the truth.

10. Your learnings/ folder

Every chapter ends with three to five takeaways under For your notes. They exist to be written down by hand, in your own words, because restating an idea is what tells you whether you have it.

mkdir -p ~/taskd-learnings
cd ~/taskd-learnings
git init

Use the same four headings every time, so 27 files stay searchable:

# ch08 — CRUD done properly

## What now works that didn't before

## The decision, and why (one paragraph)

## The error I hit and what it meant

## The sentence worth memorising

Because they are identical, you can grep the set: grep -A3 "error I hit" ~/taskd-learnings/*.md gives you every mistake you have made and what it turned out to be. Start now, with ~/taskd-learnings/fm02.md.

Common mistakes (and the quick fix)

Install failures are in §6. These are the other four that catch people in their first hour.

Check yourself

1. go run . gives go: cannot find main module. Most likely cause, and the first command you run to check?
2. command not found: sqlc appears right after go install ...sqlc... reported no errors. Was the install broken?
3. A compile error says ./cmd/api/main.go:47:12. What are the 47 and the 12?
4. Your file is 30 lines and the error is ./main.go:31:1: syntax error: unexpected EOF, expected }. Where do you look?
5. curl -i localhost:4000/v1/healthcheck prints curl: (7) Failed to connect.... Name the two most likely causes.
6. Why does this book insist on WSL2 for Windows readers rather than PowerShell?
7. make says *** missing separator. Stop. after you copy a Makefile out of a PDF. Which single character is wrong?
8. docker compose version succeeds. Does that mean Docker can run a database for you?

FAQ

Can I use Vim, Neovim, GoLand or Zed instead of VS Code?

Yes. Nothing here depends on VS Code. What matters is that your editor runs gofmt on save and shows compile errors as you type, because Chapter 26’s pipeline fails builds over formatting. Most editors get both from gopls. VS Code is recommended as the shortest path to a working setup, not as the better tool.

Do I really need Docker? Can’t I install PostgreSQL directly?

You can, and then you own its upgrades, configuration, startup and eventual removal. Chapter 5 brings up PostgreSQL 17 in one command; Chapter 13 adds DragonflyDB to the same file, Chapter 21 a mail server, Chapter 18 Prometheus. By the end you run four services you never installed. That is what the one-time cost of Docker buys.

This is a lot of setup before writing any code. Is that normal?

Yes, and this is the smallest version of it. A working professional does it once per machine and forgets about it for a year. It feels heavy because you are doing all of it in one sitting while also learning what each piece is for. It does not recur.

Why can’t I use apt install golang? It’s one command.

Distributions freeze package versions for their release cycle, and this book needs Go 1.24+. apt often hands you something a year or more old, and the failure surfaces later as a confusing compile error rather than as “wrong version”. The tarball takes two extra minutes and removes the whole category of problem.

My version numbers are higher than the ones printed here. Is that a problem?

No — higher is fine for everything in the list. These transcripts were produced on Go 1.25, newer than the 1.24 the book pins, and the book’s code is unaffected. Where a version difference genuinely matters, the chapter that cares says so.

Before you start Chapter 1

Tick every line. Each is a command you have actually run, not a thing you believe is true.

• [ ] I can open a terminal, and pwd tells me where I am.
• [ ] I know Tab completes names, Up arrow repeats commands, and Ctrl-C stops a running program.
• [ ] (Windows only) I am typing in an Ubuntu WSL2 window, my project will live under ~, and git config --global core.autocrlf false has been run.
• [ ] go version prints 1.24 or higher.
• [ ] echo $PATH | tr ':' '\n' | grep go shows a line ending in /go/bin.
• [ ] git --version prints a 2.x version.
• [ ] docker compose version prints v2 or newer, and Docker Desktop is running.
• [ ] curl --version and jq --version both print a version.
• [ ] make --version says GNU Make.
• [ ] My editor is installed, the Go extension is installed, and format-on-save is on.
• [ ] go run . in ~/go-practice printed hello from Go.
• [ ] I have deliberately broken that program, read the compile error, and fixed it.
• [ ] ~/taskd-learnings exists and is a Git repository.

All thirteen ticked means your machine will not be the reason anything fails for the next 27 chapters. Go to Chapter 1 (Introduction: what we’re building and why this shape).

Where we are

You have a terminal you can navigate, seven working tools, a scratch Go module, and a notes repository. You have compiled and run a Go program, broken it on purpose, read the compiler’s answer, and fixed it. Nothing in taskd exists yet — Chapter 2 creates the first folder.

Still ahead in the warm-up: How the web actually works makes curl -i output fully legible, Go in one sitting teaches the language, and SQL and databases in one sitting teaches the database. Those three are reference chapters — read once, return to often. This one you should never need again.

For your notes

Copy these into ~/taskd-learnings/fm02.md, in your own words.

1. command not found is a PATH problem, never a code problem. The shell searched every folder in PATH and found nothing by that name. Either it is not installed, or it is not where the shell looks.
2. go install puts binaries in $(go env GOPATH)/bin, which is not on PATH by default. Fixing this before Chapter 5 saves the single most common wasted half-hour in this book.
3. A Go compile error gives you file, line, column, type and name. Read all five before changing anything. For syntax errors, the line is where the compiler gave up — the mistake is usually above it.
4. Silence means success. Unix tools print nothing when they work; unexpected text is the signal.
5. Format-on-save is not cosmetic. Chapter 26’s pipeline fails builds that are not gofmt-clean. Tick the box on day one and the problem never exists.

How the web actually works

By the end of Chapter 2 you will type this and see a reply:

curl -i localhost:4000/v1/healthcheck

Every character in that line, and every line of the reply, is a decision somebody made about how two programs talk. This warm-up explains all of them. When you finish it, that command and its output will contain nothing mysterious — no line you skim past, no number you take on faith.

What you’ll be able to do by the end

• Explain what a server is, in terms of a process and a port, without hand-waving.
• Read a raw HTTP request and response byte by byte, and say what each part is for.
• Predict which status code taskd returns for a given mistake, and why.
• Read curl -i output line by line, and know which flag produced which part of it.
• Say what Authorization: Bearer ..., Content-Type, and Idempotency-Key do, and which chapter of this book builds each one.

Time: ~45 minutes reading, ~15 minutes typing. Nothing here requires Go, and nothing here requires taskd to exist yet.

You need before starting: a terminal, curl, and nc. All three are set up in Before you begin. Prove them with curl --version and nc -h.

1. Two computers, one conversation

Two programs want to talk. One of them speaks first and asks for something; the other listens and answers. That is the whole idea, and it has two names.

The word server misleads beginners constantly, so let us kill the confusion now: a server is a program, not a machine. People say “the server is down” about a computer in a rack, but in this book “server” always means the running program. Your laptop can run six servers at once. taskd is a server. So is PostgreSQL. So is the thing that hands your browser this page.

What does a server program actually do? Almost nothing, most of the time. It asks the operating system for a port (section 2), and then it blocks — sits there doing nothing, using no CPU — until a connection arrives. When one does, it wakes up, reads the request, works out an answer, writes it back, and goes back to waiting. taskd will do this a few thousand times a second and be bored the whole time.

In Chapter 2 (The skeleton) you write the line that does the waiting:

err := srv.ListenAndServe()

ListenAndServe does not return while the server is healthy. It is the “sit there and wait” instruction. The only reason your program ever gets past that line is that something went wrong, which is why the very next line logs an error and exits.

Run this. Nothing is listening on port 4000 yet, so ask for something and watch the failure:

curl -i http://localhost:4000/v1/healthcheck

You should see:

curl: (7) Failed to connect to localhost port 4000 after 0 ms: Couldn't connect to server

That message is not a bug. It is the correct answer to “talk to the program on port 4000” when there is no program on port 4000. You will see it perhaps thirty times while working through this book, and every single time it means the same thing: the server isn’t running. Not broken — absent.

2. Addresses, ports, localhost, and DNS

To reach a server you need two numbers.

One special address matters more than all the others while you are learning: 127.0.0.1, the machine you are sitting at. It has a name, localhost, and traffic to it never touches a network card, a router, or the internet. It goes out of your program and straight back into your own machine. Every curl localhost:4000 in this book is your laptop talking to itself.

Here is the port map for this whole book. You will meet all six.

Only one program may hold a given port at a time. That rule is the cause of a failure you will meet within a week:

listen tcp :4000: bind: address already in use

It means an older copy of taskd is still running in a terminal tab you forgot about. Find it, Ctrl-C it, start again.

Where DNS comes in

Humans do not remember 104.20.23.154. So there is a directory service that turns names into addresses.

localhost is the exception that proves the rule: it is resolved from a local file (/etc/hosts), never from the network, which is why curl localhost:4000 works with your Wi-Fi off. Chapters 1 through 26 never need real DNS. Chapter 27 (Going live) does, because that is where api.yourdomain.com has to point at a real machine.

Run this. Prove localhost resolves to your own machine:

ping -c 1 localhost

The first two lines you should see:

PING localhost (127.0.0.1): 56 data bytes
64 bytes from 127.0.0.1: icmp_seq=0 ttl=64 time=0.077 ms

The address in the parentheses is the point. Your time in milliseconds will differ; it is a round trip that never left the building.

3. TCP: a reliable pipe between two programs

An IP address and a port get you to the right program. Something still has to carry the bytes, in order, without losing any. That job belongs to TCP.

Opening a connection takes a short exchange (the “three-way handshake” — three small messages before any of your data moves). That handshake costs a round trip, which is exactly why Chapter 6 (Connecting with pgx) keeps a pool of already-open database connections instead of opening a fresh one per query. Reusing a connection means skipping the handshake.

Two properties of TCP shape everything that follows:

1. It is a stream of bytes, not messages. TCP delivers POST /v1/tasks HTTP/1.1... as a flow of characters. It has no idea where your request ends. Something on top has to say “this request is 20 bytes of body long, stop reading there” — that something is HTTP.
2. A connection is a resource that stays open. Each one costs the server a small amount of memory and a file descriptor. That is why Chapter 2 sets IdleTimeout: time.Minute — a connection nobody is using gets closed rather than accumulating until the server runs out.

Run this. Become a program that holds a port. In one terminal:

nc -l 4000

nc (netcat) now owns port 4000 and waits, exactly like a server. In a second terminal:

curl -i --max-time 3 http://localhost:4000/v1/healthcheck

Look at terminal one. It printed the request curl sent. Nothing answers, so curl gives up after three seconds — but the connection was real, and you just watched a request arrive. Press Ctrl-C in terminal one to release the port.

4. HTTP: text, over that pipe — the request

TCP gives you a pipe. HTTP is the language two programs agree to speak through it, and its best-kept secret is that it is plain text you could type by hand.

Here is a real request. This is not an illustration: it is what nc captured when curl sent a POST /v1/tasks on my machine, printed exactly as it arrived.

POST /v1/tasks HTTP/1.1
Host: localhost:4000
User-Agent: curl/8.7.1
Accept: */*
Authorization: Bearer FKF6PMGT2WQ3ZKNJ5X7YQ4RVDA
Content-Type: application/json
Content-Length: 20

{"title":"buy milk"}

Four parts, always in this order:

1. The request line — POST /v1/tasks HTTP/1.1. Three fields separated by spaces: the method (what kind of operation), the path (which resource), the protocol version.
2. Headers — one per line, Name: value. Facts about the request rather than the request itself.
3. A blank line — the marker that says “headers finished, body begins”. Not decoration. Without it the server cannot tell where headers stop.
4. The body — the actual payload, here 20 bytes of JSON. GET requests usually have none.

The bytes underneath

Every line above ends with two invisible characters, not one: a carriage return (\r, hex 0d) and a line feed (\n, hex 0a). Here is the same request as raw bytes, from xxd:

00000000: 504f 5354 202f 7631 2f74 6173 6b73 2048  POST /v1/tasks H
00000010: 5454 502f 312e 310d 0a48 6f73 743a 206c  TTP/1.1..Host: l
00000020: 6f63 616c 686f 7374 3a34 3030 300d 0a55  ocalhost:4000..U
...
000000a0: 6a73 6f6e 0d0a 436f 6e74 656e 742d 4c65  json..Content-Le
000000b0: 6e67 7468 3a20 3230 0d0a 0d0a 7b22 7469  ngth: 20....{"ti
000000c0: 746c 6522 3a22 6275 7920 6d69 6c6b 227d  tle":"buy milk"}

Find 0d0a 0d0a near the end. That is the blank line: two line-endings back to back, headers over, body starting at {. And Content-Length: 20 is how the server knows to read exactly 20 more bytes and then stop — TCP would happily let it wait forever otherwise.

Run this. Capture your own raw request. In terminal one:

nc -l 4000 > raw-request.txt

In terminal two:

curl -s --max-time 3 -X POST http://localhost:4000/v1/tasks \
  -H "Authorization: Bearer FKF6PMGT2WQ3ZKNJ5X7YQ4RVDA" \
  -H "Content-Type: application/json" \
  -d '{"title":"buy milk"}'

Then cat raw-request.txt, and if you want the bytes, xxd raw-request.txt.

5. The response

The reply has the same shape with one difference: instead of a request line it opens with a status line.

This is a real response, captured from the Chapter 2 healthcheck handler:

HTTP/1.1 200 OK
Content-Type: application/json
Date: Sat, 15 Aug 2026 19:00:14 GMT
Content-Length: 68
Connection: close

{"status":"available","environment":"development","version":"0.1.0"}

• HTTP/1.1 200 OK — protocol version, a three-digit status code, and a human-readable label. Programs read the number; the words are for people.
• Content-Type: application/json — “interpret this body as JSON”. Chapter 2’s handler sets this by hand; Chapter 8’s writeJSON helper sets it for every response in the book.
• Date and Content-Length — added by Go’s HTTP server without you asking.
• Blank line, then the body.

Order is not negotiable, and it will bite you in Chapter 8: headers, then the status line, then the body. Once the status has been sent, header changes are silently ignored. That is why writeJSON sets every header first and calls w.WriteHeader(status) second.

Run this. Be the server yourself, by hand. In terminal one:

nc -l 4002

In terminal two:

curl -i --max-time 20 http://localhost:4002/v1/healthcheck

Terminal one prints curl’s request and waits. Now type this into terminal one — the blank line matters — and press Enter, then Ctrl-D:

HTTP/1.1 200 OK
Content-Type: application/json

{"status":"available"}

Terminal two prints it as a real HTTP response. You have written a web server with your fingers.

6. Methods, and the two words that matter

The method is the verb: what kind of operation this is. Six of them appear in this book.

These two words are not academic. POST is the only method here that is neither, and that single fact is why Chapter 23 (Hardening the edge) exists. Picture it: a client posts a new task, the network stalls, the client gives up and retries. Did the first one land? Nobody knows, and now there might be two tasks. The fix is the client sending an Idempotency-Key header so the server can recognise the retry and replay its old answer instead of creating a second task.

OPTIONS is the one you never write. Browsers send it on their own before certain cross-site requests, asking permission first. Chapter 23 handles it by mounting CORS before authentication, because a browser’s OPTIONS carries no token and would otherwise be rejected with a 401.

Run this. curl uses GET by default, POST when you pass -d, and whatever you name with -X. Confirm with the capture trick from section 4 — start nc -l 4000 and try:

curl -s --max-time 3 -X DELETE http://localhost:4000/v1/tasks/7

The first word nc prints is DELETE.

7. Status codes

The three-digit number in the status line. Its first digit is the family, and knowing the five families is most of the job.

The 4xx/5xx split is the one that matters for a career. A 4xx is a bill sent to the caller: fix your request. A 5xx is an apology and a page for whoever is on call. Getting this backwards — returning 500 when a user sent bad JSON — turns your error dashboard into noise.

Here is every code taskd returns, and where it is built:

Two of those will look wrong to you, and both are deliberate:

• 402 Payment Required was reserved decades ago and left unused. Chapter 17 repurposes it as a sales signal: hitting your plan’s task limit returns 402 with a code and an upgrade URL, which is a far better client experience than a generic 403.
• 404 for other people’s tasks. Task 7 exists, but it belongs to another user. The honest answer is 403 Forbidden — and Chapter 12 returns 404 instead, on purpose. A 403 confirms the task exists, which lets an attacker map your database by counting responses. 404 tells them nothing.

Run this. Real transcripts from a server speaking taskd’s exact response bytes. -s silences curl’s progress meter; -i prints the headers. A wrong method on a real path:

HTTP/1.1 405 Method Not Allowed
Allow: GET
Date: Sat, 15 Aug 2026 19:00:07 GMT
Content-Length: 0

A validation failure, once Chapter 8 is done:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
Content-Length: 39

{"error":{"title":"must be provided"}}

Note the Allow: GET header on the 405. The router adds it without being asked, telling the client which methods would have worked.

8. Headers

A header is a Name: value line carrying a fact about the message. Names are case-insensitive (Content-Type and content-type are the same header), and there can be many of them.

Three headers deserve real understanding now.

Content-Type answers “how should I interpret these bytes?”. A body is bytes; bytes alone do not say whether they are JSON, an image, or a form. taskd sends Content-Type: application/json on every response and expects it on every request body. Chapter 16 (Stripe II) shows what happens when you forget that a body is bytes first and JSON second: Stripe’s signature is computed over the raw bytes, so decoding before verifying destroys the proof.

Authorization answers “who are you?”. taskd uses the Bearer scheme:

Authorization: Bearer FKF6PMGT2WQ3ZKNJ5X7YQ4RVDA

That 26-character string is not decorative. Chapter 11 generates 16 random bytes and encodes them in base32, which produces exactly 26 characters — and the authentication middleware rejects anything of a different length before it touches the database.

Idempotency-Key answers “is this a retry?”. The client invents a unique string per real attempt and repeats it on retries; the server remembers the response and replays it. Chapter 23 implements this on the two POSTs that hurt to duplicate: creating a task and starting a checkout.

Everything else taskd touches, so none of it ambushes you later:

Names beginning X- are conventional non-standard headers. There is nothing magic about the prefix; it is a habit that means “this one is ours”.

Run this. Ask any public site for headers only — -I sends a HEAD request, which asks for the response headers without the body:

curl -I https://example.com

You should see a status line and roughly ten headers. The exact set varies by site and by day; what matters is that you recognise the shape.

9. The body, and what JSON is

The body is whatever bytes follow the blank line. taskd’s bodies are always JSON.

Rules that catch everyone once:

• Keys are always quoted strings. {title: "x"} is not JSON; {"title": "x"} is.
• Double quotes only. 'x' is not a JSON string.
• No trailing comma after the last element.
• No comments.

Here is a real response body from a POST /v1/tasks, reformatted for reading:

{
  "task": {
    "id": 7,
    "created_at": "2026-03-14T09:12:41Z",
    "updated_at": "2026-03-14T09:12:41Z",
    "title": "buy milk",
    "notes": "",
    "status": "open",
    "priority": "none",
    "due_at": null,
    "version": 1,
    "user_id": 3
  }
}

Three things to notice, each of which becomes a decision later in the book:

1. The envelope. The task is wrapped in {"task": ...} rather than sent bare. Chapter 8 argues this out: one map literal buys you a place to add siblings — Chapter 9 adds pagination metadata alongside — without breaking clients that already parse task.
2. "due_at": null. JSON has a value that means “nothing here”. Chapter 8 leans on the difference between a key set to null and a key absent altogether, because that is how a PATCH distinguishes “clear the due date” from “leave the due date alone”.
3. "version": 1. Not decoration. Chapter 8’s optimistic locking sends this number back on an update; if it no longer matches, somebody else edited the row first and you get a 409.

How JSON becomes Go

JSON is text. Go values are typed structures. Something must translate, and in Go that something is driven by struct tags — small strings attached to struct fields naming their JSON key. You will meet exactly this in Chapter 8, and it is worth seeing once now:

// internal/db/models.go — this is taskd's real Task type (Chapter 7 generates it)
type Task struct {
	ID        int64      `json:"id"`
	CreatedAt time.Time  `json:"created_at"`
	Title     string     `json:"title"`
	DueAt     *time.Time `json:"due_at"`
	Version   int32      `json:"version"`
}

The tag json:"created_at" says: when turning this into JSON, call the field created_at; when reading JSON, fill it from created_at. The Go field is CreatedAt because Go’s capitalisation rule makes uppercase names visible outside their package, and the JSON world prefers snake_case. Go in one sitting covers structs and tags properly; this is here so the words are not new when you meet them.

Run this. Check whether a piece of JSON is valid before you blame the server:

echo '{"title":"buy milk"}' | jq .

jq reprints it, indented. Now break it on purpose:

echo '{title:"buy milk"}' | jq .

jq reports a parse error. This is exactly the mistake that earns you a 400 from taskd.

10. What an API is, and what REST does and doesn’t mean

taskd has no web pages. It has endpoints: a method plus a path that together name one operation. GET /v1/tasks/7, POST /v1/tasks, DELETE /v1/tasks/7.

Three conventions are visible in every taskd path:

• Nouns, not verbs. The path names a thing (/v1/tasks); the method says what to do to it. Not /v1/createTask.
• Plural collections, singular members. /v1/tasks is the collection; /v1/tasks/7 is one member of it.
• A version prefix. Everything lives under /v1 so that a breaking /v2 can exist one day without stranding old clients. Chapter 2 puts this in place on the first day, which costs nothing then and is nearly impossible to retrofit later.

REST is the name for this style. Honestly stated: in industry, “REST API” means “a JSON API over HTTP with sensible paths and methods”. The original definition is stricter and demands things almost nobody implements. This book uses the loose meaning and does not pretend otherwise. What actually matters is the discipline underneath it: predictable paths, methods that mean what they say, status codes that are true, and the same response shape everywhere.

One more distinction, because it prevents a whole class of confusion later: the JSON you get is a representation, not the row. {"id":7,"title":"buy milk",...} is a rendering of a database row, chosen by us. Chapter 11 shows the point sharply — the Token type has a field that is deliberately never rendered, so the plaintext token can exist in Go and never appear in JSON.

Run this. Read taskd’s whole API surface in one sitting once you reach it — the file is cmd/api/routes.go, and Chapter 24 (Documenting the API) turns it into a browsable page at http://localhost:4000/docs.

11. What curl does

The flags this book uses:

Two behaviours surprise people. -d implies POST, so curl -d '{"title":"x"}' localhost:4000/v1/tasks is a POST without you saying so — but it sends Content-Type: application/x-www-form-urlencoded unless you pass -H "Content-Type: application/json". taskd’s readJSON will still parse it, and a stricter server would not. Add the header; it is what the book does.

Here is curl -i output split into its parts. Real transcript, from a server writing taskd’s Chapter 8 bytes:

HTTP/1.1 201 Created                                  <- status line
Content-Type: application/json                        <- headers begin
Location: /v1/tasks/7
Referrer-Policy: strict-origin-when-cross-origin
Vary: Authorization
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Date: Sat, 15 Aug 2026 19:01:12 GMT
Content-Length: 192
                                                      <- the blank line
{"task":{"id":7,"created_at":"2026-03-14T09:12:41Z",...

Everything above the blank line came from -i. Without it you get the last line only.

-v shows more: lines starting * are curl narrating, > is what it sent, < is what came back. A real trace, trimmed:

* Host localhost:4000 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
*   Trying [::1]:4000...
* Connected to localhost (::1) port 4000
> GET /v1/healthcheck HTTP/1.1
> Host: localhost:4000
> User-Agent: curl/8.7.1
> Accept: */*
>
* Request completely sent off
< HTTP/1.1 200 OK
< Content-Type: application/json
< Date: Sat, 15 Aug 2026 19:01:16 GMT
< Content-Length: 68
<
{"status":"available","environment":"development","version":"0.1.0"}

Sections 1 through 5 of this chapter are all visible in those fifteen lines: name resolved, connection opened, request text written, response text read.

Run this. Point verbose curl at anything, including nothing:

curl -v --max-time 3 http://localhost:4000/v1/healthcheck

With no server up, you get the resolve lines and then the connection failure — which is itself useful: it proves the name resolved fine and the connection is what failed.

12. What sits in front: proxies, load balancers, and HTTPS

taskd listens on port 4000 and speaks plain HTTP. In production it does not face the internet directly. Something sits in front.

Chapter 27 (Going live) puts Caddy in that position, with a config the size of a haiku:

api.yourdomain.com {
    reverse_proxy localhost:4000
}

Caddy takes the public traffic on ports 443 and 80, and forwards each request to taskd on 4000. That buys three things at once: HTTPS certificates obtained and renewed automatically, one place to add or remove app instances, and a firewall rule that stops anyone reaching port 4000 directly.

It also creates the trap Chapter 14 warns about. Once Caddy forwards every request, taskd sees Caddy’s address as the client for all of them — one “IP” absorbing the entire rate limit. The fix is the X-Forwarded-For header, which the proxy adds to record the original client, trusted only because Caddy is the sole route to the port.

HTTPS, at a level you can hold

Three things it gives you, in plain terms:

1. Nobody in between can read the bytes. On plain HTTP, the coffee shop’s Wi-Fi can read your Authorization: Bearer ... header and become you. This is the whole reason bearer tokens require HTTPS.
2. Nobody in between can change the bytes. Tampering is detected.
3. You are talking to who you think. The server presents a certificate signed by an authority your machine already trusts, vouching that it really is api.yourdomain.com.

The handshake that sets this up costs an extra round trip or two before any HTTP flows, which is another reason connections are reused rather than reopened.

Run this (needs internet). Watch a TLS handshake happen:

curl -sv -o /dev/null https://example.com

Among the * lines you should see a TLS handshake, Client hello, a Certificate step, an SSL connection using TLSv1.3 line, and a Server certificate: block naming a subject and an expiry date. The exact ciphers and dates depend on the site and the day. That block is your machine checking it is talking to the real example.com.

13. One request, end to end

Everything in this chapter, in one picture. This traces a single POST /v1/tasks — chosen because it is the one request that exercises every idea at once: name resolution, TCP, HTTP, authentication, middleware, SQL, JSON, and a status code with a header attached.

  you type:
    curl -i -H "Authorization: Bearer FKF6PMGT2WQ3ZKNJ5X7YQ4RVDA" \
            -H "Content-Type: application/json" \
            -d '{"title":"buy milk"}' \
            localhost:4000/v1/tasks

  ┌─────────────┐
  │    curl     │  1. resolve the name:  "localhost" ──▶ 127.0.0.1
  │  (client)   │  2. open a TCP connection to 127.0.0.1 : 4000
  └──────┬──────┘  3. write HTTP text down it:
         │              POST /v1/tasks HTTP/1.1
         │              Host: localhost:4000
         │              Authorization: Bearer FKF6PMGT2WQ3ZKNJ5X7YQ4RVDA
         │              Content-Type: application/json
         │              Content-Length: 20
         │              (blank line)
         │              {"title":"buy milk"}
         ▼
  ┌──────────────────────────────────────────────────────────────┐
  │  the taskd process, waiting on port 4000                     │
  │                                                              │
  │  4. http.Server accepts, parses, starts ONE goroutine  ch. 2 │
  │                                                              │
  │  5. middleware rings, outermost first:                       │
  │       secureHeaders ─────────────────────────────────  ch.23 │
  │        └▶ cors ──────────────────────────────────────  ch.23 │
  │            └▶ recoverPanic ──────────────────────────  ch. 4 │
  │                └▶ metrics ───────────────────────────  ch.18 │
  │                    └▶ logRequest ────────────────────  ch.19 │
  │                        └▶ authenticate ──────────────  ch.11 │
  │                            └▶ requireAuthenticated ──  ch.11 │
  │                                └▶ requireActivated ──  ch.21 │
  │                                    └▶ rateLimitUser ─  ch.14 │
  │                                        └▶ idempotent   ch.23 │
  │                                                              │
  │  6. chi matches POST /v1/tasks ──▶ createTaskHandler   ch. 8 │
  │  7. handler: readJSON ▶ validate ▶ quota gate ▶ INSERT  ch.17 │
  │  8. Postgres returns the new row                       ch. 5 │
  │  9. writeJSON: headers, then status line, then body    ch. 8 │
  └──────────────────────────┬───────────────────────────────────┘
                             │ 10. bytes travel back down
                             ▼     the same TCP connection
  ┌──────────────────────────────────────────────────────────────┐
  │  HTTP/1.1 201 Created                                        │
  │  Content-Type: application/json                              │
  │  Location: /v1/tasks/7                                       │
  │  (blank line)                                                │
  │  {"task":{"id":7,"title":"buy milk",...}}                    │
  └──────────────────────────────────────────────────────────────┘

  11. curl prints it and exits. The connection stays open but idle
      for up to IdleTimeout (1 minute), ready to be reused.

Walking the numbers:

1. Resolve. localhost becomes 127.0.0.1 from a local file. In production this is a real DNS lookup (Chapter 27).
2. Connect. A TCP handshake opens a reliable pipe to port 4000. If nothing is listening, you get the Failed to connect error from section 1 and steps 3 onward never happen.
3. Write. curl formats the method, path, headers, blank line, and body as text and sends it.
4. Accept. Go’s http.Server reads the text, turns it into an *http.Request, and runs the rest of this list in its own goroutine — a lightweight thread, so a slow request blocks nobody else. Chapter 2 sets this up; Go in one sitting explains goroutines.
5. Middleware. Ten layers wrap the handler like rings of an onion, each one able to answer early. authenticate hashes the bearer token and finds the user. rateLimitUser can end the request right here with a 429. Chapter 4 (A server that dies well) builds the first ring.
6. Route. chi compares method and path against the registered routes and picks the handler. Wrong method here is what produced the 405 in section 7.
7. Handle. Decode the JSON (400 on failure), validate it (422 on failure), check the plan’s quota (402 on failure), then insert a row.
8. Database. Postgres returns the created row, including the id and version it assigned.
9. Respond. writeJSON sets Location, sets Content-Type, writes status 201, writes body. In that order, because after the status nothing else can be set.
10. Return. The response text goes back down the same connection that carried the request.
11. Idle. curl exits. The connection lingers, unused, until IdleTimeout closes it — which is why the next request is faster: no new handshake.

Every chapter of this book adds a ring, a step, or a failure mode to this one picture.

Come back here when

Common mistakes

Check yourself

1. A server program is running but no request has arrived for ten minutes. What is it doing, and roughly how much CPU is it using?
2. You run curl localhost:4000/v1/healthcheck and get Failed to connect. Name two different causes, and the one place you would look first.
3. Which of GET, POST, PUT, DELETE are idempotent? Why does the answer matter to Chapter 23?
4. A client sends {"title":""} to POST /v1/tasks with a valid token. Which status code comes back, and why is it not 400?
5. In an HTTP message, what separates the headers from the body, and what happens if it is missing?
6. Why does taskd return 404 rather than 403 when you ask for a task belonging to another user?
7. You see HTTP/1.1 200 OK but the body is {"error":"..."}. What has the developer done wrong?
8. What does Content-Type: application/json actually change about the bytes in the body?

FAQ

Can I skip this and start Chapter 2? You can, and you will get output. But Chapter 2’s closing paragraph — the end-to-end trace that is the mental model for the entire book — is written in this vocabulary. Reading it without this chapter is reading a summary of a film you have not seen.

Why is HTTP plain text? Isn’t that wasteful? Yes, and it was still the right call. Text is inspectable: you can read it with nc, type it by hand, and debug it with your eyes, which is why you could do both of those things in this chapter. HTTP/2 and HTTP/3 are binary and faster, and Go’s server speaks HTTP/1.1 to curl here. The shape is identical either way; only the encoding on the wire changes.

Do I need to memorise all fifteen status codes? No. Memorise the five families and the rule that 4xx blames the caller while 5xx blames you. The table in section 7 is a reference to return to; you will absorb the specific codes as each chapter builds the case for one.

Everyone says “REST API”. Is what we’re building actually REST? By the loose industry meaning, yes. By the original academic definition, no — and almost nothing you have ever used is either. This book uses the term the way working developers use it and does not pretend the strict version is being implemented.

Why does the book run everything on localhost instead of a real server? Because it removes an entire category of problem from your first twenty-six chapters. No DNS, no certificates, no firewalls, no deploy step between writing a line and seeing it work. Chapter 27 adds the real hostname and the certificate, and by then the only new thing is the outside world.

Is it safe to send an Authorization header over plain HTTP on localhost? On localhost, yes — the bytes never leave your machine. Over a network, no. A bearer token is a password in a header; anything that can read the connection becomes that user. That is section 12’s entire point, and it is why Chapter 27 puts Caddy and TLS in front before the service faces the internet.

Where we are

You can now read an HTTP request and response by eye, name what each part does, predict which status code a given mistake earns, and explain what curl -i is showing you. Nothing in the rest of the book will use a networking word this chapter has not defined.

What is still missing, and where it arrives: the Go language (Go in one sitting), SQL and databases (SQL and databases in one sitting), and the actual server that answers these requests (Chapter 2, The skeleton).

For your notes — copy these into learnings/fm03.md in your own words:

1. A server is a process that holds a port and waits. “Connection refused” means absent, not broken — check the terminal where you started it.
2. An HTTP message is a first line, headers, a blank line, and a body. The blank line is the only thing separating headers from body, and it is two line-endings back to back.
3. 4xx blames the caller, 5xx blames the server. 400 means “I couldn’t read it”; 422 means “I read it and it’s wrong”. Getting this backwards makes your error dashboard useless.
4. Safe means “changes nothing”; idempotent means “twice equals once”. POST is neither, which is the entire reason idempotency keys exist in Chapter 23.
5. Content-Type does not change the bytes, only how they are interpreted. A body is bytes first and JSON second — a distinction that becomes load-bearing when Chapter 16 verifies a Stripe signature.

Go in one sitting

This is the Go you need to read and write this book’s code — no more, and no less. It is not a tour of the language. Every idea below appears in taskd, most of them within the first eight chapters, and each one is introduced with the same shape you will meet again later, so that when Chapter 8 (CRUD done properly) puts a pointer inside a struct tag inside an anonymous struct, you recognise all three pieces.

Time: about ninety minutes to read, about two hours if you type and run everything. You should type and run everything.

If you already write Go: skim the section headings, read section 4 (Errors are values), section 9 (Functions as values, closures, and interfaces), and the Common mistakes table, then go to Chapter 1. Nothing else here will surprise you.

If you have never programmed at all: read Before you begin first — it installs Go and teaches you the terminal. Then come back. Do not try to memorise this chapter. You are building recognition, not recall. When Chapter 4 (A server that dies well) shows you a channel, you want the reaction “I have seen that arrow before”, not “I know exactly what that does”. The book re-explains every idea at the moment it does real work.

Set up a scratch module first

Everything in this chapter runs in a throwaway project. Keep it outside taskd — you will create that in Chapter 2 (The skeleton), and you don’t want practice files in it.

mkdir -p ~/go-practice
cd ~/go-practice
go mod init example.com/go-practice

You should see:

go: creating new go.mod: module example.com/go-practice

Every code block in this chapter names the file to put it in, like this:

// go-practice/hello/main.go — scratch, delete the whole folder when you're done

Create that folder and that file, paste, run. Delete ~/go-practice when you finish the chapter.

The six ideas that repeat on every page

Before the detail, here is the map. These six sentences are the whole book’s Go, compressed. Read them now; they will mean more after each section, and you can come back to this list as a summary.

1. Structs are labelled boxes; methods are functions attached to them. type config struct { port int } defines a box with a typed slot. A method is a function with a receiver before its name: in func (app *application) serve() error, the (app *application) part means “this function belongs to application values, and inside it, app refers to the one it was called on.” When you later read app.logger.Info(...) inside a handler, that is the whole trick — the handler is a method, so it carries its dependencies with it. → sections 5 and 6

2. Pointers: & takes an address, * means “pointer to”. app := &application{...} creates one struct and hands back its address; everything holding that pointer shares the same struct rather than copies. That is why the whole app agrees about one logger and one database pool. You rarely need more pointer theory than this: &thing to share it, *Type in a signature to receive a shared one. → section 6

3. Errors are ordinary values, and if err != nil is the rhythm of Go. Functions that can fail return an error as their last result. You check it immediately, every time: handle it, wrap it with context (fmt.Errorf("loading config: %w", err)), or return it upward. There are no exceptions to catch; the visible chain of if err != nil blocks is the error-handling story, and its repetitiveness is a feature — failure paths are impossible to miss in review. → section 4

4. defer schedules cleanup for when the function exits. defer pool.Close() runs when the surrounding function returns — no matter which return path is taken, even a panic. It keeps acquisition and release on adjacent lines, which is why you will see it after every resource we open. → section 10

5. Interfaces describe behaviour; anything with the right methods satisfies them. http.Handler is “anything with a ServeHTTP(w, r) method.” Our router satisfies it, every middleware takes one and returns one, and no type ever declares “I implement Handler” — having the method is the declaration. This is why middleware compose so freely. → section 9

6. Goroutines and channels: cheap concurrency, typed pipes. go someFunc() runs a function concurrently; ch := make(chan error) makes a pipe; ch <- v sends into it and <-ch blocks until something arrives. The standard library already runs every HTTP request in its own goroutine — which is why shared things need care (Chapter 14’s mutex) and why graceful shutdown (Chapter 4) is a small conversation between two goroutines over a channel. → section 11

Each of these gets re-explained in place the first time it does real work. This chapter means none of them will ambush you.

1. A program, a package, a module

Go is a compiled language. You write text; a program called the compiler turns it into a single executable file of machine instructions — a binary — and that binary is what runs. Nothing has to be installed on the server for it to work. That property is the reason Chapter 25 (Docker) can ship taskd as a 15 MB image with no operating system inside it.

A program starts at the function main in the package main.

// go-practice/hello/main.go — scratch
package main

import "fmt"

func main() {
	fmt.Println("taskd practice: hello")
}

cd ~/go-practice
go run ./hello

taskd practice: hello

Line by line:

• package main — this file belongs to the package called main. That specific name is what tells Go “this package builds an executable”. taskd’s cmd/api/*.go files all start with package main; internal/validator/validator.go starts with package validator, which builds a library instead.
• import "fmt" — bring in the standard library’s formatting package. You must import what you use, and you must not import what you don’t (see Common mistakes).
• func main() — the entry point. Exactly one per program.
• fmt.Println — the package name, a dot, the function.

go run, go build, go install

Three commands, three different outcomes.

go build -o bin/hello ./hello
ls -l bin/hello
./bin/hello

The binary is around 2.3 MB for a program that prints one line — Go bakes its runtime and garbage collector into every binary. That fixed cost stops mattering the moment your program does anything real.

Imports, modules, and internal/

go.mod names your module. In taskd it says module github.com/yourname/taskd, and that name is the prefix for importing the project’s own packages:

import "github.com/yourname/taskd/internal/validator"

Third-party code arrives with go get, which downloads it and records the exact version in go.mod:

go get github.com/go-chi/chi/v5@latest

go: added github.com/go-chi/chi/v5 v5.3.1

One folder name is special. Anything under a directory called internal/ cannot be imported from outside your own module — the compiler enforces it, it is not a naming convention. Try it from another project and you get:

use of internal package example.com/moda/internal/data not allowed

That is why taskd puts its database code, validator and cache wrapper in internal/: they are this program’s private parts, and the toolchain guarantees nobody else builds against them.

Capital letters are the access control

Go has no public or private keyword. A name starting with a capital letter is visible to other packages; a lowercase name is private to its own package. That rule is load-bearing in Chapter 10 (Users and passwords), where the Password struct keeps plaintext lowercase so it is structurally impossible for another package — or the JSON encoder — to read it.

2. Values: variables, types, zero values

Every value in Go has a type, fixed when the variable is created, and the compiler checks every use of it. There are two ways to create a variable.

// go-practice/values/main.go — scratch
package main

import "fmt"

const version = "0.1.0" // never changes while the program runs

type config struct {
	port int
	env  string
}

func main() {
	var cfg config // every field gets its zero value
	fmt.Printf("zero config: %+v\n", cfg)

	cfg.port = 4000
	cfg.env = "development"
	addr := fmt.Sprintf(":%d", cfg.port) // := declares and assigns
	fmt.Println(version, addr, cfg.env)
}

go run ./values

zero config: {port:0 env:}
0.1.0 :4000 development

• var cfg config — declare a variable of type config without giving it a value. It is not garbage and it is not an error: it holds the zero value of every field.
• addr := fmt.Sprintf(...) — declare and assign in one step, with the type inferred from the right-hand side. := only works inside a function.
• const version = "0.1.0" — a constant, fixed at compile time. Chapter 2 declares exactly this line; Chapter 25 turns it into a var so the build can stamp the real Git commit into it.

Zero values are a design tool, not an accident. Chapter 9 (Listing at scale) returns Metadata{} — every field zero — to mean “there are no results”, and lets the JSON encoder omit them all. Chapter 13 (Caching with DragonflyDB) treats a nil cache as a legal state meaning “running degraded, no cache today”.

The types this book uses

// go-practice/types/main.go — scratch
package main

import "fmt"

type Tier string // a named type over string: still a string, new identity

const TierPro Tier = "pro"

func main() {
	var pageSize int = 20
	var limit int32 = int32(pageSize) // conversion is always explicit
	var enabled bool                  // zero value: false
	var name string                   // zero value: ""
	var hash []byte                   // zero value: nil

	fmt.Println(limit, enabled, len(name), hash == nil)
	fmt.Printf("%q has %d bytes and %d runes\n", "héllo", len("héllo"), len([]rune("héllo")))
	fmt.Println(TierPro, string(TierPro) == "pro")
}

20 false 0 true
"héllo" has 6 bytes and 5 runes
pro true

Three things worth memorising:

1. Go never converts number types for you. int32(pageSize) is a conversion you write by hand. Leave it out and the compiler stops you — see Common mistakes.
2. A string is bytes, not characters. len("héllo") is 6, because é takes two bytes in UTF-8. []rune(s) converts to a list of characters if you need to count those instead. This matters in Chapter 10: the password rule is “at least 8 bytes long”, and it says bytes on purpose, because bcrypt has a 72-byte ceiling.
3. A named type is a new type, not an alias. type Tier string gives you a Tier that the compiler will not accept where a plain string is wanted, and vice versa, without an explicit conversion. Chapter 15 (Stripe I) uses it so a plan tier can never be confused with an arbitrary string; Chapter 19 uses type contextKey string so no other package can collide with its context keys.

3. Functions, and returning two things

A function names its parameters with their types, and its results after the parameter list.

// go-practice/funcs/main.go — scratch
package main

import (
	"fmt"
	"strconv"
)

// itoa is the real two-line helper from taskd's cmd/api/helpers.go.
func itoa(i int64) string { return strconv.FormatInt(i, 10) }

// Two results: the value, and whether it was usable. This is the shape
// of almost every function in taskd.
func readIDParam(s string) (int64, error) {
	id, err := strconv.ParseInt(s, 10, 64)
	if err != nil || id < 1 {
		return 0, fmt.Errorf("invalid id parameter: %q", s)
	}
	return id, nil
}

func main() {
	id, err := readIDParam("42")
	fmt.Println(id, err, "/v1/tasks/"+itoa(id))

	_, err = readIDParam("abc")
	fmt.Println(err)
}

42 <nil> /v1/tasks/42
invalid id parameter: "abc"

• func readIDParam(s string) (int64, error) — one parameter named s of type string, two results. When a function returns more than one value the results go in parentheses.
• The last result is an error by convention whenever a function can fail. This is not a rule the compiler enforces; it is a convention the entire language follows, and taskd follows it about 150 times.
• _, err = readIDParam("abc") — the underscore is the blank identifier: “I must accept this value and I am deliberately ignoring it.” You need it because Go refuses to compile a program with an unused variable.
• <nil> is how fmt prints a nil error. No error happened.

You will meet readIDParam and itoa again as real code in Chapter 8 (CRUD done properly), where itoa builds the Location: /v1/tasks/17 header on a freshly created task.

The format verbs

fmt.Printf and fmt.Sprintf take a template with % placeholders. The book uses six of them.

// go-practice/fmtdemo/main.go — scratch
package main

import "fmt"

func main() {
	fmt.Printf("%d\n", 4000)                     // an integer
	fmt.Printf("%s\n", "development")            // a string, bare
	fmt.Printf("%q\n", "development")            // a string, quoted
	fmt.Printf("%v\n", []string{"open", "done"}) // any value, default form
	fmt.Printf("%+v\n", struct{ Page int }{3})   // structs, with field names
	fmt.Printf("%T\n", int64(7))                 // the type, not the value
	fmt.Printf("100%% cached\n")                 // a literal percent sign
}

4000
development
"development"
[open done]
{Page:3}
int64
100% cached

%q is the one to remember: Chapter 2’s first handler hand-writes JSON with fmt.Fprintf(w, "{\"status\":\"available\",\"environment\":%q}", app.config.env) precisely because %q produces a correctly quoted JSON string. There is a seventh verb, %w, which belongs to errors and is the subject of the next section.

4. Errors are values

This is the section to read twice. Go has no exceptions. A function that can fail returns the failure as an ordinary value, and you deal with it on the next line or you have written a bug.

if err != nil {
	return err
}

That block appears about 150 times in taskd. Its repetitiveness is deliberate: every place the program can fail is visible on the page, in the normal flow of reading, rather than hidden in a jump to a handler somewhere else.

Wrapping with %w

An error from deep in the standard library says open config.toml: no such file or directory. That is true but contextless. fmt.Errorf with the %w verb adds your context while keeping the original error inside, so later code can still ask what it really was.

// go-practice/errs/main.go — scratch
package main

import (
	"errors"
	"fmt"
	"os"
)

func loadConfig(path string) error {
	// os.Open fails; we add context and keep the original with %w.
	_, err := os.Open(path)
	if err != nil {
		return fmt.Errorf("loading %s: %w", path, err)
	}
	return nil
}

func main() {
	err := loadConfig("config.toml")
	fmt.Println(err)

	// errors.Is walks the %w chain looking for one specific value.
	fmt.Println("is not-exist?", errors.Is(err, os.ErrNotExist))

	// errors.As walks it looking for one specific TYPE, and fills the var.
	var pathErr *os.PathError
	if errors.As(err, &pathErr) {
		fmt.Println("failed operation:", pathErr.Op, "on", pathErr.Path)
	}
}

loading config.toml: open config.toml: no such file or directory
is not-exist? true
failed operation: open on config.toml

Chapter 3 (Configuration and logging) contains that exact fmt.Errorf("loading %s: %w", path, err) line.

Sentinel errors and errors.Is

A sentinel error is one specific error value, declared once, compared by identity. The standard library and every serious Go package ship them: http.ErrServerClosed, pgx.ErrNoRows, io.EOF, bcrypt.ErrMismatchedHashAndPassword.

// go-practice/sentinel/main.go — scratch
package main

import (
	"errors"
	"fmt"
)

// A sentinel: one specific error value, declared once, compared by identity.
// pgx.ErrNoRows and http.ErrServerClosed are exactly this.
var ErrNoRows = errors.New("no rows in result set")

func getTask(id int64) error {
	if id != 1 {
		return fmt.Errorf("querying task %d: %w", id, ErrNoRows)
	}
	return nil
}

func main() {
	err := getTask(7)
	switch { // a tagless switch: the cases are conditions, not values
	case errors.Is(err, ErrNoRows):
		fmt.Println("404 the requested resource could not be found")
	case err != nil:
		fmt.Println("500 the server encountered a problem")
	default:
		fmt.Println("200 OK")
	}
}

404 the requested resource could not be found

That switch is not an analogy. It is the literal shape of showTaskHandler in Chapter 8: a missing row is a 404 the client caused, anything else is a 500 we caused, and telling them apart is the whole job.

errors.As is the same question about types rather than values, and it takes a pointer to a variable which it fills in on success. Chapter 8’s readJSON uses it four times to work out which way a JSON body was malformed — syntax error, wrong type, body too large — and turn each one into a message a client can act on.

5. Structs, and the methods that hang off them

// go-practice/structs/main.go — scratch
package main

import (
	"encoding/json"
	"fmt"
	"time"
)

// The real shape from taskd's internal/data/tokens.go, trimmed.
type Token struct {
	Plaintext string    `json:"token"`
	Hash      []byte    `json:"-"` // "-" means: never appear in JSON
	UserID    int64     `json:"-"`
	Expiry    time.Time `json:"expiry"`
}

func main() {
	t := Token{Plaintext: "FKF6...", Hash: []byte{1, 2}, UserID: 7,
		Expiry: time.Date(2026, 1, 2, 3, 4, 5, 0, time.UTC)}

	js, _ := json.Marshal(t)
	fmt.Println(string(js))
	fmt.Printf("%+v\n", struct{ Title, Notes string }{"buy milk", ""})
}

{"token":"FKF6...","expiry":"2026-01-02T03:04:05Z"}
{Title:buy milk Notes:}

Three things are happening.

Struct literals. Token{Plaintext: "FKF6...", ...} builds one, naming the fields. Always name them — the positional form exists but breaks silently the day someone adds a field.

Struct tags. The backtick string after a field’s type is a note for libraries. json:"token" says “call this field token in JSON”; json:"-" says “never put this field in JSON at all”. Those tags on Token are a security mechanism, not a formatting one: in Chapter 11 (Stateful tokens), the plaintext token goes to the client exactly once, and the hash we store is made structurally incapable of appearing in any response.

Anonymous structs. struct{ Title, Notes string }{"buy milk", ""} declares a struct type and makes one, in a single expression, with no name. Chapter 8 uses this for every request body: the shape is written where it is used and nowhere else, so there is no chance of a leftover type drifting away from the endpoint it describes.

Methods and receivers

A method is a function attached to a type. The (f Filters) part before the name is the receiver.

// go-practice/methods/main.go — scratch
package main

import "fmt"

type Filters struct{ Page, PageSize int }

// Value receiver: gets a COPY. Fine — it only reads.
func (f Filters) Offset() int32 { return int32((f.Page - 1) * f.PageSize) }

// Pointer receiver: gets the address. Required — it writes.
func (f *Filters) NextPage() { f.Page++ }

func main() {
	f := Filters{Page: 3, PageSize: 20}
	fmt.Println("offset:", f.Offset())

	f.NextPage() // Go rewrites this as (&f).NextPage()
	fmt.Println("page now:", f.Page, "offset:", f.Offset())
}

offset: 40
page now: 4 offset: 60

Offset is real code — it is how Chapter 9 turns “page 3, 20 per page” into OFFSET 40 for PostgreSQL.

The difference between the two receivers is the single most common source of quiet bugs for people new to Go:

• Value receiver (f Filters) — the method gets a copy. Changes it makes are thrown away when the method returns. Use it when the method only reads.
• Pointer receiver (f *Filters) — the method gets the address. Changes it makes are visible to the caller. Use it when the method writes, or when the struct is large enough that copying it is wasteful.

Get it wrong and nothing complains:

// go-practice/valuereceiver/main.go — scratch
package main

import "fmt"

type Filters struct{ Page int }

// The bug: a VALUE receiver mutating its copy. Compiles. Does nothing.
func (f Filters) NextPageBroken() { f.Page++ }

func main() {
	f := Filters{Page: 1}
	f.NextPageBroken()
	fmt.Println("page:", f.Page) // still 1
}

page: 1

Why every handler in this book is a method on *application

This is the pattern the next twenty-five chapters hang off, so it is worth ten minutes now.

A handler needs a logger, a database pool, a cache, a mailer and the config. There are three ways to give it those, and Chapter 2 argues them out: package-level global variables (any code can secretly change them, tests can’t swap them), a dependency-injection framework (machinery for a problem Go does not have), or one struct holding every shared dependency, with every handler written as a method on it.

// go-practice/appstruct/main.go — scratch
package main

import (
	"log/slog"
	"os"
)

// The dependency container, in miniature. Every handler in taskd is a
// method on *application — that is how they all reach the logger.
type application struct {
	logger *slog.Logger
	env    string
}

func (app *application) healthcheck() {
	app.logger.Info("healthcheck", "status", "available", "env", app.env)
}

func main() {
	logger := slog.New(slog.NewTextHandler(os.Stdout, nil))
	app := &application{logger: logger, env: "development"} // & = address of
	app.healthcheck()
}

time=2026-08-16T00:34:19.235+05:30 level=INFO msg=healthcheck status=available env=development

(Your timestamp will differ — that is your own clock.)

app.logger inside the method is not magic. app is the receiver; logger is a field on it. Every handler you write from Chapter 2 onward starts func (app *application) for exactly this reason, and it costs one line per handler to buy testability forever: Chapter 20 (Testing what matters) builds a different application with a test database and a logger pointed at io.Discard, and the handlers cannot tell the difference.

6. Pointers

// go-practice/pointers/main.go — scratch
package main

import "fmt"

type Task struct{ Title, Notes string }

func main() {
	a := Task{Title: "original"}
	b := a  // a COPY
	p := &a // a POINTER to the same struct
	b.Title = "copy edited"
	p.Title = "pointer edited" // same as (*p).Title
	fmt.Println(a.Title, "|", b.Title, "|", p.Title)

	var missing *Task // zero value of any pointer is nil
	fmt.Println("missing == nil:", missing == nil)
}

pointer edited | copy edited | pointer edited
missing == nil: true

Editing through p changed a. Editing b did not, because b := a copied the struct. That is the entire idea.

nil is the zero value of a pointer: “this points at nothing”. Reading a field through a nil pointer crashes the program at runtime — see Common mistakes.

Pointer-as-optional, and the PATCH overlay

Here is the second job pointers do in this book, and it is the one that surprises people. A pointer can be nil, and a plain string cannot. So *string can express something string cannot: “the client did not send this field at all”, as distinct from “the client sent an empty string”.

// go-practice/overlay/main.go — scratch
package main

import (
	"encoding/json"
	"fmt"
)

type Task struct{ Title, Notes string }

func main() {
	// Every field is a POINTER, so nil means "the client didn't send it".
	var input struct {
		Title *string `json:"title"`
		Notes *string `json:"notes"`
	}
	json.Unmarshal([]byte(`{"title":"renamed"}`), &input)

	task := Task{Title: "old title", Notes: "keep me"}
	if input.Title != nil {
		task.Title = *input.Title // * reads the value the pointer points at
	}
	if input.Notes != nil {
		task.Notes = *input.Notes
	}
	fmt.Printf("%+v\n", task)
}

{Title:renamed Notes:keep me}

That is Chapter 8’s updateTaskHandler, complete. A PATCH request that mentions only title leaves notes alone, because input.Notes is nil. Without pointers, an absent notes and an "notes": "" would both arrive as "" and the handler would silently wipe the field.

Chapter 8 also documents the honest limitation of this trick: a client cannot set a value back to null, because absent and explicit-null both decode to nil.

7. Slices and maps

Two collection types, and you need both from Chapter 8 onward.

Slices

// go-practice/slices/main.go — scratch
package main

import (
	"encoding/json"
	"fmt"
)

func main() {
	statuses := []string{"open", "doing", "done"} // slice literal
	fmt.Println(len(statuses), statuses[0], statuses)

	// make(type, length, capacity): 0 items now, room for 3 without regrowing.
	tasks := make([]string, 0, len(statuses))
	for i, s := range statuses { // range gives index, value
		tasks = append(tasks, fmt.Sprintf("%d:%s", i, s))
	}
	fmt.Println(tasks)

	var nilSlice []string
	empty := []string{}
	a, _ := json.Marshal(nilSlice)
	b, _ := json.Marshal(empty)
	fmt.Println("nil ->", string(a), " empty ->", string(b))
}

3 open [open doing done]
[0:open 1:doing 2:done]
nil -> null  empty -> []

• len(s) is the count. Indexes start at 0.
• append(s, v) returns a new slice with v on the end. You must assign the result back — append(s, v) on its own line does nothing useful.
• make([]T, 0, n) creates a slice with zero items but room for n, so append never has to reallocate. Chapter 9 writes make([]db.Task, 0, len(rows)) for exactly this reason.
• for i, s := range statuses walks the slice, giving index and value. Use _ for either if you do not need it.

The last two lines are the reason Chapter 9 is fussy about make([]db.Task, 0, ...) rather than var tasks []db.Task: a nil slice encodes as JSON null, and an empty slice encodes as []. A client parsing "tasks": null has to write a special case; a client parsing "tasks": [] does not. One character of Go, a real difference to every consumer of your API.

Maps

// go-practice/maps/main.go — scratch
package main

import "fmt"

func main() {
	errs := make(map[string]string) // the validator's Errors map
	errs["title"] = "must be provided"

	// AddError's rule: keep only the FIRST message per field.
	if _, exists := errs["title"]; !exists { // the comma-ok idiom
		errs["title"] = "must not be more than 500 bytes long"
	}
	fmt.Println(errs, len(errs) == 0)

	// Reading a missing key is legal: you get the zero value, not a crash.
	fmt.Printf("missing key -> %q\n", errs["notes"])

	delete(errs, "title")
	fmt.Println("after delete:", errs, "valid:", len(errs) == 0)
}

map[title:must be provided] false
missing key -> ""
after delete: map[] valid: true

That is internal/validator/validator.go from Chapter 8, almost line for line: Errors is a map[string]string from field name to human message, AddError keeps only the first message per field using the comma-ok check, and Valid() is len(v.Errors) == 0.

The comma-ok idiom — value, ok := m[key] — is how you tell “the key is missing” from “the key is present with the zero value”. You will see the same two-result shape again for type assertions in section 9 and channel receives in section 11.

Bytes, arrays, and the [:] you will meet in Chapter 11

// go-practice/bytes/main.go — scratch
package main

import (
	"crypto/sha256"
	"encoding/hex"
	"fmt"
)

func main() {
	plaintext := "SIU4EQPHHUB6D5RQ3TPCJTPWLE" // a 26-char taskd token

	// Sum256 returns [32]byte — a fixed-size ARRAY, not a slice.
	hash := sha256.Sum256([]byte(plaintext))

	// hash[:] reslices the array into a []byte, which is what the
	// database column and every function here actually want.
	fmt.Println(len(plaintext), "chars ->", len(hash[:]), "bytes")
	fmt.Println(hex.EncodeToString(hash[:]))
}

26 chars -> 32 bytes
16482678a497a115496d3e25860738ccd6bdd5f299d813ddf28a51b2c14d2db0

An array has a length fixed in its type — [32]byte is a different type from [16]byte. Go’s crypto functions return arrays; almost everything else wants slices; x[:] is the conversion. []byte("some string") goes the other way, from text to bytes. Chapter 11 writes t.Hash = hash[:] on the line after sha256.Sum256, and now you know why.

8. Loops, if, switch, and asking what type something is

Go has exactly one loop keyword, for, in four shapes:

for i := 0; i < 10; i++ { }      // the counting loop
for i, v := range collection { } // over a slice, map, string or channel
for condition { }                // "while"
for { }                          // forever, until you return or break

Chapter 14 (Rate limiting) uses the infinite form for its cleanup goroutine; Chapter 21 uses for range ticker.C to do something once an hour.

// go-practice/switches/main.go — scratch
package main

import "fmt"

func plan(tier string) int {
	switch tier { // expression switch: no fallthrough, no break needed
	case "pro":
		return 10_000
	case "business":
		return -1 // -1 means unlimited
	default:
		return 100
	}
}

func main() {
	for _, t := range []string{"free", "pro", "business"} {
		fmt.Println(t, plan(t))
	}
	// if with an init statement: n exists only inside the if/else.
	if n := plan("pro"); n == -1 {
		fmt.Println("unlimited")
	} else {
		fmt.Println("cap:", n)
	}
}

free 100
pro 10000
business -1
cap: 10000

Two Go-specific details:

• switch does not fall through. No break needed; each case ends by itself.
• if can carry an init statement. if n := plan("pro"); n == -1 creates n, then tests it, and n exists only inside that if/else. taskd uses this constantly: if err := app.readJSON(w, r, &input); err != nil {.

You have already seen the tagless switch in section 4 — switch { with conditions as cases. Read it as a tidier if / else if / else. It is the house style for error triage.

Type switches and type assertions

any is a value of any type at all — Go’s escape hatch when the type genuinely varies. taskd uses it in type envelope map[string]any, the wrapper every response body wears. To get a real type back out you assert.

// go-practice/typeswitch/main.go — scratch
package main

import "fmt"

// envelope is taskd's response wrapper: keys to anything at all.
type envelope map[string]any

func describe(v any) string {
	switch x := v.(type) { // type switch: which concrete type is inside?
	case string:
		return "string of " + fmt.Sprint(len(x)) + " chars"
	case map[string]string:
		return fmt.Sprint(len(x), " field errors")
	default:
		return fmt.Sprintf("something else (%T)", x)
	}
}

func main() {
	e := envelope{"error": "rate limit exceeded"}
	fmt.Println(describe(e["error"]))
	fmt.Println(describe(map[string]string{"title": "must be provided"}))
	fmt.Println(describe(402))

	// The comma-ok assertion: ok is false instead of panicking.
	s, ok := e["error"].(int)
	fmt.Println(s, ok)
}

string of 19 chars
1 field errors
something else (int)
0 false

v.(string) on its own would panic if v were not a string. v, ok := v.(string) gives you a boolean instead. Chapter 19 (Logging that pays rent) uses the comma-ok form to pull a request ID out of a context, and Chapter 11 uses the panicking form on purpose — a handler that cannot find its user was wired to the wrong route, which is a programmer error that should be loud.

9. Functions as values, closures, and interfaces

This section contains the hardest single idea in the book. It is worth slowing down for; Chapter 4 (A server that dies well) leans on it, and so does every middleware from Chapter 11 to Chapter 23.

Functions are values

A function can be stored in a variable, passed to another function, and returned from one.

// go-practice/closure/main.go — scratch
package main

import (
	"fmt"
	"strings"
)

func main() {
	// A function value: assign it, pass it, call it later.
	transform := func(s string) string {
		s = strings.TrimPrefix(s, "TASKD_")
		return strings.ReplaceAll(strings.ToLower(s), "__", ".")
	}
	fmt.Println(transform("TASKD_DB__DSN"))
	fmt.Println(transform("TASKD_STRIPE__SECRET_KEY"))

	// A closure: this function CAPTURES prefix from the surrounding scope.
	prefix := "u:42:"
	key := func(name string) string { return prefix + name }
	fmt.Println(key("tasks"), key("ver"))
}

db.dsn
stripe.secret_key
u:42:tasks u:42:ver

transform is Chapter 3’s real config loader function, the one that turns the environment variable TASKD_DB__DSN into the config key db.dsn. It is handed to koanf as a value, and koanf calls it once per environment variable.

Capture is a real hazard, not trivia. Chapter 21 (Background work and transactional email) starts background goroutines with closures and is careful to capture user and token rather than the *http.Request — because the request is gone by the time the goroutine runs.

Interfaces

This is the part that feels strange coming from other languages: there is no implements keyword. A type satisfies an interface by having the methods, full stop. The compiler works it out.

// go-practice/iface/main.go — scratch
package main

import (
	"fmt"
	"io"
	"os"
	"strings"
)

// io.Writer is an interface the standard library declares:
//
//	type Writer interface { Write(p []byte) (n int, err error) }
//
// Anything with that method satisfies it. Nobody says "implements".
func greet(w io.Writer, name string) { fmt.Fprintf(w, "hello %s\n", name) }

func main() {
	greet(os.Stdout, "stdout") // a file satisfies io.Writer
	var b strings.Builder      // so does a string builder
	greet(&b, "builder")
	fmt.Print(b.String())
	fmt.Println(io.Discard != nil) // and so does the bin
}

hello stdout
hello builder
true

Three unrelated types — a file, a string builder, a discard sink — all work, because all three have a Write method. greet never learns which is which.

http.Handler, the interface this whole book is built on

http.Handler is one method:

type Handler interface {
	ServeHTTP(ResponseWriter, *Request)
}

“Anything that can answer an HTTP request.” Your router satisfies it. Every middleware takes one and returns one. And because writing a whole type for every handler would be tedious, the standard library ships an adapter: http.HandlerFunc is a function type with a ServeHTTP method that calls the function. So http.HandlerFunc(myFunc) converts a plain function into a Handler.

// go-practice/handler/main.go — scratch
package main

import (
	"fmt"
	"net/http"
	"net/http/httptest"
)

// http.Handler is: type Handler interface { ServeHTTP(ResponseWriter, *Request) }
// http.HandlerFunc converts a plain function into something with that method.
func healthcheck(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "application/json")
	fmt.Fprintf(w, `{"status":"available","version":%q}`, "0.1.0")
}

func main() {
	var h http.Handler = http.HandlerFunc(healthcheck)

	rec := httptest.NewRecorder() // a fake ResponseWriter that records
	h.ServeHTTP(rec, httptest.NewRequest("GET", "/v1/healthcheck", nil))

	fmt.Println(rec.Code, rec.Header().Get("Content-Type"))
	fmt.Println(rec.Body.String())
}

200 application/json
{"status":"available","version":"0.1.0"}

That is Chapter 2’s first handler, running, without a server or a browser. httptest.NewRecorder is a fake ResponseWriter that keeps what was written — the same trick Chapter 20 uses to test the real thing.

Middleware: the pattern that runs the codebase

Put the last two ideas together — functions are values, and http.Handler is an interface — and you get middleware:

A middleware is a function that takes a handler and returns a new handler, which does something before and/or after calling the original.

// go-practice/middleware/main.go — scratch
package main

import (
	"fmt"
	"net/http"
	"net/http/httptest"
)

// A middleware: takes a handler, returns a handler that wraps it.
func announce(label string, next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		fmt.Println("->", label)
		next.ServeHTTP(w, r) // call through
		fmt.Println("<-", label)
	})
}

func main() {
	var h http.Handler = http.HandlerFunc(
		func(w http.ResponseWriter, r *http.Request) { fmt.Println("   handler") })

	h = announce("logRequest", h)   // registered second -> inner
	h = announce("recoverPanic", h) // registered last  -> outermost

	h.ServeHTTP(httptest.NewRecorder(), httptest.NewRequest("GET", "/", nil))
}

-> recoverPanic
-> logRequest
   handler
<- logRequest
<- recoverPanic

That output is the onion diagram, proven by running it:

request ──▶ recoverPanic ──▶ logRequest ──▶ router ──▶ your handler
response ◀── recoverPanic ◀── logRequest ◀── router ◀──┘

Everything cross-cutting in taskd is this shape: panic recovery and request logging (Chapter 4), authentication (Chapter 11), rate limits (Chapter 14), metrics (Chapter 18), idempotency keys (Chapter 23). Understand these fifteen lines and you have understood a third of the codebase in advance.

10. defer, panic, recover

defer schedules a function call for when the surrounding function returns — by any route, including a panic.

// go-practice/deferdemo/main.go — scratch
package main

import "fmt"

func withLoop() {
	for i := 1; i <= 3; i++ {
		defer fmt.Println("deferred", i) // NOT at the end of each iteration
	}
	fmt.Println("loop finished")
}

func main() {
	fmt.Println("open pool")
	defer fmt.Println("close pool") // runs last, whatever happens
	withLoop()
	fmt.Println("main body done")
}

open pool
loop finished
deferred 3
deferred 2
deferred 1
main body done
close pool

Two facts, both visible in that output:

1. defer is per-function, not per-block. The three deferred calls inside the loop did not run at the end of each iteration; they ran when withLoop returned. Chapter 4 names this as the misconception everyone has once.
2. Deferred calls run in reverse order, last scheduled first. That is what you want for cleanup: you release in the opposite order you acquired.

taskd uses defer for pool.Close(), cancel() on every context with a timeout, ticker.Stop(), mu.Unlock(), wg.Done(), and the Prometheus in-flight gauge decrement. In each case the acquire and the release sit on adjacent lines, so you can see at a glance that they match.

panic and recover

Panics are rare in normal Go. You do not use them for expected failures — that is what errors are for. But they happen: a nil pointer dereference, an index out of range, a write to a nil map, or a deliberate panic() for a condition that means the programmer wired something wrong.

Unhandled, one panic in one handler kills the entire server process, taking every other user’s in-flight request with it. So taskd’s outermost middleware catches them.

// go-practice/recoverdemo/main.go — scratch
package main

import (
	"fmt"
	"net/http"
	"net/http/httptest"
)

func recoverPanic(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		defer func() {
			if err := recover(); err != nil { // stops the unwinding
				w.Header().Set("Connection", "close")
				http.Error(w, fmt.Sprintf("500: %s", err), 500)
			}
		}()
		next.ServeHTTP(w, r)
	})
}

func main() {
	h := recoverPanic(http.HandlerFunc(
		func(w http.ResponseWriter, r *http.Request) { panic("missing user value") }))
	rec := httptest.NewRecorder()
	h.ServeHTTP(rec, httptest.NewRequest("GET", "/v1/tasks", nil))
	fmt.Println(rec.Code, rec.Header().Get("Connection"), rec.Body.String())
}

500 close 500: missing user value

A handler panicked; the client got a clean 500 and the process survived. That is Chapter 4’s recoverPanic, with its real logger swapped for http.Error. recover() only works inside a deferred function — which is exactly why the defer func() { ... }() shape exists.

11. Concurrency: goroutines, channels, mutex, WaitGroup

You are already concurrent

Here is the fact that makes this section non-optional: Go’s HTTP server runs every request in its own goroutine, whether you asked for it or not. You will never write go in a handler, and your handlers still run simultaneously.

// go-practice/pergoroutine/main.go — scratch
package main

import (
	"fmt"
	"net/http"
	"net/http/httptest"
	"sync"
)

func main() {
	// Every handler signals "I'm here", then waits for the other four.
	// If the server served requests one at a time, this would hang forever.
	var arrived sync.WaitGroup
	arrived.Add(5)
	srv := httptest.NewServer(http.HandlerFunc(
		func(w http.ResponseWriter, r *http.Request) {
			arrived.Done()
			arrived.Wait()
			fmt.Fprintln(w, "served")
		}))
	defer srv.Close()

	var clients sync.WaitGroup
	for i := 0; i < 5; i++ {
		clients.Add(1)
		go func() { defer clients.Done(); srv.Client().Get(srv.URL) }()
	}
	clients.Wait()
	fmt.Println("five handlers ran at the same time; nobody wrote `go`")
}

five handlers ran at the same time; nobody wrote `go`

If the server had processed those requests one after another, the first handler would have waited forever for four colleagues who never arrived, and the program would hang. It printed instead. Five handlers were alive at once.

That is the whole justification for the next three sub-sections, and for Chapter 14’s mutex.

Channels

// go-practice/chans/main.go — scratch
package main

import (
	"fmt"
	"time"
)

func main() {
	shutdownError := make(chan error) // an unbuffered typed pipe

	go func() { // a goroutine: runs alongside main, does not block it
		time.Sleep(50 * time.Millisecond)
		fmt.Println("goroutine: draining requests")
		shutdownError <- nil // send; blocks until someone receives
	}()

	fmt.Println("main: serving traffic")
	err := <-shutdownError // receive; blocks until something arrives
	fmt.Println("main: drain result =", err)
}

main: serving traffic
goroutine: draining requests
main: drain result = <nil>

Read the arrows as direction of travel: ch <- v puts v into the pipe, <-ch takes something out. An unbuffered channel is a handshake — the sender waits for a receiver and vice versa. make(chan os.Signal, 1) in Chapter 4 is a buffered channel with room for one value, so the operating system can drop a signal in without waiting for anyone.

This example is Chapter 4’s graceful shutdown in miniature. The real version: the main goroutine sits in srv.ListenAndServe() serving traffic, a second goroutine sleeps until the operating system delivers Ctrl-C or Docker’s stop signal, and the result of the shutdown travels back to main over shutdownError. The channel exists because the answer to “did every in-flight request finish in time?” is computed in one goroutine and needed in the other.

Data races, and the mutex that fixes them

Two goroutines writing the same map at the same time is not a subtle bug. It is a crash.

// go-practice/race/main.go — scratch, this one crashes on purpose
package main

import (
	"fmt"
	"sync"
)

func main() {
	clients := make(map[string]int)
	var wg sync.WaitGroup

	for i := 0; i < 100; i++ {
		wg.Add(1) // count one more worker BEFORE starting it
		go func() {
			defer wg.Done() // count it off however this function exits
			clients["1.2.3.4"]++
		}()
	}
	wg.Wait() // block until the counter is back to zero
	fmt.Println("count:", clients["1.2.3.4"])
}

fatal error: concurrent map writes

Run it again with Go’s race detector and you get a diagnosis instead of a corpse:

go run -race ./race

==================
WARNING: DATA RACE
Read at 0x00c0001240f0 by goroutine 10:
  runtime.mapassign_fast64ptr()

The fix is a mutex — a lock only one goroutine can hold at a time.

// go-practice/mutex/main.go — scratch
package main

import (
	"fmt"
	"sync"
)

func main() {
	var (
		mu      sync.Mutex
		clients = make(map[string]int)
		wg      sync.WaitGroup
	)
	for i := 0; i < 100; i++ {
		wg.Add(1)
		go func() {
			defer wg.Done()
			mu.Lock()         // one goroutine past this line at a time
			defer mu.Unlock() // released however this function exits
			clients["1.2.3.4"]++
		}()
	}
	wg.Wait()
	fmt.Println("count:", clients["1.2.3.4"])
}

count: 100

Both sync types are in that one program, and both are in taskd:

• sync.Mutex — Chapter 14 (Rate limiting) keeps a map[string]*client of per-IP rate limiters, written by every request goroutine. The mutex is what stops it crashing. Its code comment says: “the lock on the door: Lock() admits one goroutine; everyone else queues at Unlock().”
• sync.WaitGroup — a counter. Add(1) before starting work, Done() when it finishes, Wait() blocks until the counter is zero. Chapter 21 puts one on the application struct so that Chapter 4’s shutdown can wait for background emails to finish sending before the process exits.

select, briefly

select waits on several channels at once and takes whichever is ready first.

// go-practice/selectdemo/main.go — scratch
package main

import (
	"fmt"
	"time"
)

func main() {
	done := make(chan string)
	go func() { time.Sleep(300 * time.Millisecond); done <- "query finished" }()

	select { // wait on several channels; the first one ready wins
	case msg := <-done:
		fmt.Println(msg)
	case <-time.After(100 * time.Millisecond):
		fmt.Println("timed out first")
	}
}

timed out first

12. context: deadlines and cancellation

A context.Context is a value carried down through function calls that answers one question: “should I still be doing this?” Every function that talks to the network takes one as its first parameter.

// go-practice/ctx/main.go — scratch
package main

import (
	"context"
	"fmt"
	"time"
)

func slowQuery(ctx context.Context) error {
	select {
	case <-time.After(2 * time.Second):
		return nil // the query finished
	case <-ctx.Done():
		return ctx.Err() // the deadline (or the client) gave up
	}
}

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 200*time.Millisecond)
	defer cancel() // ALWAYS: releases the timer even on the happy path
	start := time.Now()
	fmt.Println(slowQuery(ctx), "after", time.Since(start).Round(50*time.Millisecond))
}

context deadline exceeded after 200ms

• context.Background() — the empty root context. Use it when nothing above you has one: in main, or in a background worker.
• context.WithTimeout(parent, d) — a child context that cancels itself after d. It returns the context and a cancel function you must always call, normally with defer cancel(). Chapter 6 (Connecting with pgx/v5) writes exactly this to give the database five seconds to answer at boot or fail the startup.
• r.Context() — inside a handler, the request’s own context. It is cancelled the moment the client disconnects. taskd passes it into every database call, roughly sixty times, which is why a hung-up client stops costing you a connection.

Values in a context

A context can also carry request-scoped values.

// go-practice/ctxvalue/main.go — scratch
package main

import (
	"context"
	"fmt"
)

// A private key type, so no other package can collide with ours.
type contextKey string

const requestIDKey = contextKey("request_id")

func main() {
	ctx := context.WithValue(context.Background(), requestIDKey, "9f2c1ab30e77")

	// Coming back out, the value is an `any` — assert it back to a string.
	id, ok := ctx.Value(requestIDKey).(string)
	fmt.Println(id, ok)

	missing, ok := context.Background().Value(requestIDKey).(string)
	fmt.Printf("%q %v\n", missing, ok)
}

9f2c1ab30e77 true
"" false

That is cmd/api/context.go, near enough exactly. The named key type is not decoration: if the key were the plain string "user", any package in the program could overwrite it by accident. A private named type makes collision impossible.

Chapter 11 stores the authenticated user this way, so that middleware can identify a user once and every handler downstream can read it. Chapter 19 stores a request ID the same way, so every log line from one request shares an identifier you can grep for.

13. JSON, one generic, and tests

encoding/json

JSON is text; a Go struct is not. encoding/json converts in both directions, and struct tags say how the field names map.

// go-practice/jsondemo/main.go — scratch
package main

import (
	"encoding/json"
	"fmt"
	"strings"
)

func main() {
	var input struct {
		Title    string `json:"title"`
		Priority string `json:"priority"`
	}

	body := strings.NewReader(`{"title":"buy milk","priority":"high"}`)
	dec := json.NewDecoder(body)
	dec.DisallowUnknownFields() // a typo'd key becomes an error, not silence
	fmt.Println(dec.Decode(&input), input)

	bad := json.NewDecoder(strings.NewReader(`{"titel":"typo"}`))
	bad.DisallowUnknownFields()
	fmt.Println(bad.Decode(&input))

	js, _ := json.Marshal(map[string]any{"task": input})
	fmt.Println(string(js))
}

<nil> {buy milk high}
json: unknown field "titel"
{"task":{"title":"buy milk","priority":"high"}}

Four things you will use in Chapter 8:

• json.Marshal(v) turns a Go value into []byte of JSON. writeJSON marshals to memory first, so that a half-failed encode can never reach a client who has already been told 200 OK.
• json.NewDecoder(r).Decode(&v) reads JSON from a stream — a request body — into a Go value. Note the &: the decoder needs the address so it can fill your variable in.
• DisallowUnknownFields() turns a client’s typo into an error. Without it, {"titel": "..."} decodes cleanly, saves nothing, returns 200, and the client files the bug against you.
• Only exported (capitalised) fields are encoded or decoded. A lowercase field is invisible to encoding/json — which is how Chapter 10 guarantees a plaintext password can never leak into a response.

The one generic in this book

// go-practice/generics/main.go — scratch
package main

import (
	"fmt"
	"slices"
)

// The book's only generic. [T comparable] = "T is any type you can
// compare with ==". permitted ...T is variadic: zero or more Ts.
func PermittedValue[T comparable](value T, permitted ...T) bool {
	return slices.Contains(permitted, value)
}

var Statuses = []string{"open", "doing", "done"}

func main() {
	fmt.Println(PermittedValue("doing", Statuses...)) // ... spreads the slice
	fmt.Println(PermittedValue("urgent", Statuses...))
	fmt.Println(PermittedValue(402, 200, 201, 404)) // same function, ints
}

true
false
false

PermittedValue is real, unmodified, from internal/validator/validator.go. The square brackets declare a type parameter: one function that works for strings today and integers tomorrow. The ...T is a variadic parameter — any number of arguments — and at the call site Statuses... spreads a slice into them.

This is the only generic function in taskd. Go’s generics can do considerably more; the book does not need it to.

Tests

Chapter 20 (Testing what matters) needs three facts, and here they are with a test you can run.

A test lives in a file ending _test.go, in the same package, in a function called TestSomething taking *testing.T. The Go house style is table-driven: one slice of cases, one loop.

// go-practice/pagination/metadata.go — scratch
package pagination

type Metadata struct {
	CurrentPage, PageSize, FirstPage, LastPage int
	TotalRecords                               int64
}

func CalculateMetadata(total int64, page, pageSize int) Metadata {
	if total == 0 {
		return Metadata{} // the zero value: every field 0
	}
	return Metadata{
		CurrentPage: page, PageSize: pageSize, FirstPage: 1,
		LastPage:     int((total + int64(pageSize) - 1) / int64(pageSize)),
		TotalRecords: total,
	}
}

// go-practice/pagination/metadata_test.go — scratch
package pagination

import "testing"

func TestCalculateMetadata(t *testing.T) {
	tests := []struct { // the table: one anonymous struct per case
		name           string
		total          int64
		page, pageSize int
		wantLast       int
	}{
		{"exact fit", 100, 1, 20, 5},
		{"partial last page", 101, 1, 20, 6},
		{"empty", 0, 1, 20, 0},
	}
	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) { // a named sub-test per row
			got := CalculateMetadata(tt.total, tt.page, tt.pageSize)
			if got.LastPage != tt.wantLast {
				t.Errorf("LastPage = %d, want %d", got.LastPage, tt.wantLast)
			}
		})
	}
}

go test ./pagination/ -v

=== RUN   TestCalculateMetadata
=== RUN   TestCalculateMetadata/exact_fit
=== RUN   TestCalculateMetadata/partial_last_page
=== RUN   TestCalculateMetadata/empty
--- PASS: TestCalculateMetadata (0.00s)
    --- PASS: TestCalculateMetadata/exact_fit (0.00s)
    --- PASS: TestCalculateMetadata/partial_last_page (0.00s)
    --- PASS: TestCalculateMetadata/empty (0.00s)
PASS
ok  	example.com/go-practice/pagination	0.003s

That is Chapter 20’s first test, verbatim, running against a copy of Chapter 9’s real function. Break a case on purpose — change wantLast for “partial last page” from 6 to 5 — and you get:

--- FAIL: TestCalculateMetadata (0.00s)
    --- FAIL: TestCalculateMetadata/partial_last_page (0.00s)
        metadata_test.go:20: LastPage = 6, want 5
FAIL

The sub-test name tells you which row failed. That is why t.Run is worth the extra line.

The rest of the testing vocabulary, in one table:

Common mistakes

Every error message below is real output from a real Go toolchain. Read the shape: file, line, column, then the complaint. Go’s compiler errors are unusually honest — the hard part is only believing them.

Check yourself

Answer before you look. Every question is answerable from this chapter alone.

1. var cfg config — what is in cfg.port immediately afterwards, and why is that not a bug?
2. You write func (f Filters) NextPage() { f.Page++ }, call f.NextPage(), and f.Page doesn’t change. What’s wrong?
3. In Chapter 8’s PATCH handler, why is the input struct’s Title field a *string rather than a string?
4. What is the difference between fmt.Errorf("loading: %w", err) and fmt.Errorf("loading: %v", err), and which one breaks errors.Is?
5. This middleware registration order appears in routes.go: r.Use(app.recoverPanic) then r.Use(app.logRequest). Which one sees the request first, and why does that ordering matter for panics?
6. Chapter 9 writes tasks := make([]db.Task, 0, len(rows)) instead of var tasks []db.Task. A user with no tasks calls GET /v1/tasks. What does the client receive in each case?
7. You add a sync.Mutex around a map in a handler, but the program still crashes with fatal error: concurrent map writes sometimes. Name two plausible causes.
8. Why does taskd pass r.Context() into every database call, and what specifically goes wrong in a background goroutine that does the same?

FAQ

Do I have to remember all of this before Chapter 1?

No, and trying to will slow you down. You need sections 1–6 solidly: packages, values, functions, errors, structs and methods, pointers. Everything else you need to recognise, not reproduce. The book re-teaches each idea at the moment it does real work, which is when it will actually stick.

Why does Go make me handle an error after literally every call? It’s so much typing.

Because the alternative hides the failure paths. In a language with exceptions you can read a whole function and not know which of its twelve lines can fail or where the failure ends up. In Go the failure paths are the visible half of the code. The cost is real — this book has roughly 150 if err != nil blocks — and the benefit is that no reviewer, including future you, can overlook one. Chapter 8 turns the repetition into something better by funnelling every error through one errorResponse helper.

Isn’t this a strangely small amount of Go? Where are the design patterns?

That is deliberate. taskd is about 4,000 lines of production code and it uses one generic, zero select statements, no iota, no struct embedding, no reflection, no worker pools, no custom error types and no dependency-injection framework. Go rewards boring. The interesting decisions in this book are about databases, money, caches and failure — not about the language.

I already know Python or JavaScript. What will trip me up?

Four things, in order of how often they bite. Types are checked and never converted for you — int to int32 is a conversion you write. Value versus pointer — assigning a struct copies it, which has no equivalent in either language. Unused variables and imports are compile errors, not warnings. And capitalisation is the access modifier: there is no private keyword, only a lowercase first letter.

Can I use an AI assistant to write this book’s Go for me?

You can, and you will learn nothing worth having. The specific skill this book builds is reading production code and being able to say why each line is there — including the timeouts, the error paths and the things that look redundant until the day they aren’t. Type the code. Let the assistant explain an error message if you’re stuck; do not let it write the file.

What if I want the whole language, not this subset?

Read A Tour of Go on go.dev after Chapter 8, when the shapes are familiar and the tour feels like revision rather than a firehose. Effective Go and Go by Example are the two other things worth your time. Nothing in them contradicts this chapter.

Where we are

You now have the Go this book uses, in the shapes this book uses it. Concretely, you can:

• read a Go file top to bottom and say what each declaration is: package, import, type, const, var, func, method;
• explain why func (app *application) createTaskHandler(...) starts the way it does;
• tell a value receiver from a pointer receiver and predict which one silently does nothing;
• read if err != nil { return fmt.Errorf("...: %w", err) } and know what the caller can still do with that error;
• recognise a middleware on sight, and say which one runs first;
• run a table-driven test and read its failure output.

Come back here when:

Delete your scratch module when you are done:

rm -rf ~/go-practice

For your notes

Copy these into learnings/fm04.md, in your own words:

1. Errors are values, and %w is the difference between an error you can print and an error you can react to. errors.Is compares to a known value; errors.As asks about a type. Both walk the chain that %w builds and %v destroys.

2. The receiver is the dependency-injection mechanism. func (app *application) handler(...) means the handler carries the logger, config, database pool, cache and mailer with it. One struct, one line per handler, no framework — and testable because Chapter 20 can build a different application.

3. A middleware is a function that takes a handler and returns a handler. Registered first means outermost, which means it runs first on the way in and last on the way out. Panic recovery goes outermost or it does not work.

4. Every HTTP request already runs in its own goroutine. You never wrote go, and your handlers still run simultaneously — which is why shared state needs a mutex and why go test -race is part of the build.

5. nil is a legal, useful value. A nil pointer means “absent” in a PATCH body; a nil slice encodes as JSON null where an empty one encodes as []; a nil cache means “running degraded”. Knowing which nils are deliberate is most of reading this codebase.

SQL and databases in one sitting

The original edition of this book asked you to arrive with “comfort with basic SQL”. This warm-up supplies that comfort, and nothing beyond it.

Everything here is taught with taskd’s own tables — the real tasks, users, tokens and subscriptions you will build in Chapters 5 through 22. There are no employees tables, no departments, no invented examples. By the time you finish you will have typed most of Appendix C’s final schema by hand, which means Chapter 5 (PostgreSQL and migrations) will feel like recognition rather than instruction.

Time: about 50 minutes reading, 30 minutes typing.

What you’ll be able to do by the end

• read every .sql file in this book and say what it does, line by line;
• start a throwaway PostgreSQL, connect to it, and inspect its tables;
• write INSERT, SELECT, UPDATE and DELETE with RETURNING, filters, ordering and paging;
• explain what a primary key, a foreign key, NULL, an index, a transaction and a connection pool are, and why taskd has each one;
• recognise the five constraint errors Postgres will throw at you and fix them.

You need before starting: Docker running. Check with docker ps — a table header, even an empty one, means the daemon is alive. If it prints Cannot connect to the Docker daemon, go back to Before you begin.

1. What a database is, and why not a file

Your program has data that must outlive it: tasks, users, tokens. The obvious first idea is a file — write the tasks out as JSON when the program stops, read them back when it starts.

That works for exactly one user on one machine doing one thing at a time. taskd is a web server, and web servers do many things at once. Chapter 4 (The lifecycle) puts every HTTP request in its own goroutine, so at 3pm on a Tuesday you might have forty requests inside your program simultaneously. Now the file idea breaks in four places:

A database is a program whose entire job is holding data safely while many clients read and write it concurrently. You do not open its files. You connect to it over the network and ask it questions in a language it understands. For us, that program is PostgreSQL and that language is SQL.

Run this

Start a throwaway Postgres. It is deliberately not the one Chapter 5 builds — that one arrives with Docker Compose and a Makefile, and this one gets deleted at the end of this warm-up.

docker run -d --name sql-primer \
  -e POSTGRES_USER=taskd \
  -e POSTGRES_PASSWORD=pa55word \
  -e POSTGRES_DB=taskd \
  postgres:17-alpine

It prints a long hexadecimal string — the container’s ID. Wait five seconds, then check:

docker exec sql-primer pg_isready -U taskd -d taskd

/var/run/postgresql:5432 - accepting connections

Note what is missing from the docker run: a -p flag. We are not publishing a port to your laptop, because we will talk to this database from inside its own container. That also means it cannot collide with the Postgres Chapter 5 starts on port 5432.

2. Getting a prompt: psql

psql is the official command-line client for Postgres. You type SQL, it prints tables. It is the tool the book’s make db/psql target runs for you from Chapter 5 onward.

docker exec -it sql-primer psql -U taskd -d taskd

-U taskd is the user to log in as, -d taskd is the database to open. You get a banner with the server version, Type "help" for help., and then a prompt that names the database you are in:

taskd=#

Four things to know and then we can start:

Run this

At the taskd=# prompt:

SELECT 1;

You should get a one-row, one-column table. Then \dt — which reports Did not find any relations., because the database is empty. We will fix that next.

3. Tables, rows, columns — and taskd’s first table

A table is a grid with a fixed set of named columns and any number of rows. Each column has a type, and the database refuses values of the wrong type. A row is one thing: one task, one user, one token.

Here is taskd’s first table, exactly as Chapter 5 (PostgreSQL and migrations) creates it. Type it in. The comments are the book’s own.

-- migrations/000001_create_tasks.up.sql — the real thing, type it now
CREATE TABLE tasks (
    -- IDENTITY: Postgres assigns 1, 2, 3... itself; GENERATED ALWAYS means
    -- clients can't insert their own ids (a whole bug class, deleted).
    id          bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,

    -- timestamptz = timestamp WITH time zone. now() stamps creation for free.
    created_at  timestamptz NOT NULL DEFAULT now(),
    updated_at  timestamptz NOT NULL DEFAULT now(),

    title       text        NOT NULL,
    notes       text        NOT NULL DEFAULT '',   -- empty string, never NULL

    -- The CHECK constraint makes invalid states unstorable: the database
    -- itself rejects status='banana', no matter which code path tries.
    status      text        NOT NULL DEFAULT 'open'
                CHECK (status IN ('open','done','archived')),
    priority    text        NOT NULL DEFAULT 'none'
                CHECK (priority IN ('none','low','medium','high')),

    due_at      timestamptz,                       -- the ONE honest NULL

    -- Optimistic-locking counter; ch. 8 explains the dance it powers.
    version     integer     NOT NULL DEFAULT 1
);

Postgres answers CREATE TABLE. That is the whole confirmation — SQL statements report what they did, not that they succeeded at doing it.

Run this

\dt

       List of relations
 Schema | Name  | Type  | Owner 
--------+-------+-------+-------
 public | tasks | table | taskd
(1 row)

\d tasks

                                    Table "public.tasks"
   Column   |           Type           | Collation | Nullable |           Default            
------------+--------------------------+-----------+----------+------------------------------
 id         | bigint                   |           | not null | generated always as identity
 created_at | timestamp with time zone |           | not null | now()
 updated_at | timestamp with time zone |           | not null | now()
 title      | text                     |           | not null | 
 notes      | text                     |           | not null | ''::text
 status     | text                     |           | not null | 'open'::text
 priority   | text                     |           | not null | 'none'::text
 due_at     | timestamp with time zone |           |          | 
 version    | integer                  |           | not null | 1
Indexes:
    "tasks_pkey" PRIMARY KEY, btree (id)
Check constraints:
    "tasks_priority_check" CHECK (priority = ANY (ARRAY['none'::text, 'low'::text, 'medium'::text, 'high'::text]))
    "tasks_status_check" CHECK (status = ANY (ARRAY['open'::text, 'done'::text, 'archived'::text]))

\d tasks is the single most useful command in this warm-up. Note that Postgres has rewritten your CHECK (status IN (...)) into status = ANY (ARRAY[...]), and expanded timestamptz into its formal name. What you get back is the database’s own understanding of your table, which is not always the words you typed.

4. The column types this book uses

Postgres ships dozens of types. taskd uses seven. Here they are, with where each first appears.

Four notes that will save you later:

bigint GENERATED ALWAYS AS IDENTITY is how taskd makes ids. Postgres hands out 1, 2, 3… GENERATED ALWAYS means a client cannot supply its own id — that whole class of bug is deleted at the schema level. You will see bigserial in other people’s SQL; it is the older spelling of the same idea, and this book never uses it.

Always timestamptz, never timestamp. Plain timestamp stores a wall-clock reading with no time zone attached, which will eventually corrupt someone’s Tuesday. Chapter 5 lists this as a pitfall; obey it everywhere.

citext is a Postgres extension, not a built-in — an optional add-on you switch on with CREATE EXTENSION IF NOT EXISTS citext;. Chapter 10 (Users and passwords) uses it so that Bob@example.com and bob@example.com are the same email to the database itself, not just to whichever Go function remembered to lowercase.

bytea is bytes, not text. A bcrypt hash and a SHA-256 hash are byte sequences that are not valid text in any encoding. Storing them in a text column corrupts them. You will meet this again in Chapter 11 (Stateful tokens), where tokens.hash is 32 raw bytes.

Run this

SELECT
    pg_typeof(1::bigint)      AS a,
    pg_typeof('x'::text)      AS b,
    pg_typeof(now())          AS c;

pg_typeof reports the type of a value, and :: is Postgres’ cast operator (“treat this as a bigint”). You will see bigint, text and timestamp with time zone.

5. NULL is not zero, and not “”

NULL means there is no value here — not zero, not empty string, not false. In taskd’s tasks table exactly one column is nullable: due_at. A task with due_at = NULL has no due date. A task with notes = '' has notes, and they are empty. Those are different claims and the schema keeps them different.

Chapter 5 states the rule as “NOT NULL everywhere possible”, and the reason is Go, not purity: every nullable column becomes a pointer or a pgtype wrapper in sqlc’s generated code (Chapter 7) and an if statement in every consumer. notes defaults to '' precisely so that no Go code ever has to ask whether notes exist.

The part that catches everybody: NULL is not equal to anything, including NULL. Comparing with = gives you neither true nor false — it gives you NULL, which is not true, so the row is not returned.

Run this

We need rows first. Insert them (we will unpack INSERT properly in section 8):

INSERT INTO tasks (title, notes, status, priority, due_at) VALUES
  ('write the SQL primer', '',             'open',     'high',   '2026-09-01 09:00:00+00'),
  ('buy milk',             'semi-skimmed', 'open',     'low',    NULL),
  ('file the tax return',  '',             'open',     'high',   '2026-09-30 00:00:00+00'),
  ('renew passport',       '',             'done',     'medium', NULL),
  ('water the plants',     '',             'open',     'none',   NULL),
  ('cancel the gym',       '',             'archived', 'low',    NULL);

Now the trap and its fix:

SELECT id, title FROM tasks WHERE due_at = NULL;
SELECT id, title FROM tasks WHERE due_at IS NULL;

 id | title 
----+-------
(0 rows)

 id |      title       
----+------------------
  2 | buy milk
  4 | renew passport
  5 | water the plants
  6 | cancel the gym
(4 rows)

The first query is not wrong syntax — it is silently wrong, which is worse. Always IS NULL and IS NOT NULL. You will meet IS NOT NULL doing real work in Chapter 22 (Password reset and the account lifecycle), where ConfirmPendingEmail updates a user only WHERE id = $1 AND pending_email IS NOT NULL.

6. Primary keys

A primary key is the column whose value identifies a row uniquely and forever. Postgres enforces two things about it: no two rows may share one, and it may never be NULL. It also builds an index on it automatically — that "tasks_pkey" PRIMARY KEY, btree (id) line you saw in \d tasks.

taskd’s choice is argued out loud in Chapter 5: bigint GENERATED ALWAYS AS IDENTITY, not UUID. Integers are half the size, index-friendly, and human-typeable in a debugger. The usual counter-argument — sequential ids let outsiders guess other people’s ids — is real, and taskd answers it with authorization rather than obfuscation: from Chapter 12 (Ownership: making it multi-tenant) onward every single query is scoped to the requesting user, so guessing an id gets you a 404.

Not every primary key is a number. tokens.hash is a bytea primary key — the hash is the identity of the token. And subscriptions.user_id is a primary key that is also a foreign key, which is how Chapter 15 (Stripe I) says “one subscription per user” in the schema instead of in a comment.

Run this

INSERT INTO tasks (id, title) VALUES (99, 'I choose my own id');

ERROR:  cannot insert a non-DEFAULT value into column "id"
DETAIL:  Column "id" is an identity column defined as GENERATED ALWAYS.
HINT:  Use OVERRIDING SYSTEM VALUE to override.

That refusal is the point of GENERATED ALWAYS. Ignore the HINT; taskd never wants that.

7. Constraints: the rules that live with the data

A constraint is a rule the database enforces on every write, from every code path, forever. This is the difference between validation in your application (which the next endpoint someone adds might skip) and validation in the schema (which nothing can skip).

taskd uses four kinds:

DEFAULT is applied at insert time, to rows being inserted. It does not reach back and change existing rows — which is exactly why Chapter 21 (Background work and transactional email) can run ALTER TABLE users ALTER COLUMN activated SET DEFAULT false and leave every existing account activated. Old users are grandfathered; new ones must confirm their email.

Run this

INSERT INTO tasks (title, status) VALUES ('learn SQL', 'banana');

ERROR:  new row for relation "tasks" violates check constraint "tasks_status_check"
DETAIL:  Failing row contains (7, 2026-08-15 19:03:45.319321+00, 2026-08-15 19:03:45.319321+00, learn SQL, , banana, none, null, 1).

INSERT INTO tasks (notes) VALUES ('no title here');

ERROR:  null value in column "title" of relation "tasks" violates not-null constraint
DETAIL:  Failing row contains (8, 2026-08-15 19:03:45.393303+00, 2026-08-15 19:03:45.393303+00, null, no title here, open, none, null, 1).

Read the shape of those errors: which constraint, on which table, and the entire failing row so you can see what you actually sent. Note the ids 7 and 8 in the failing rows — the identity counter moved even though the inserts failed. Gaps in id sequences are normal and mean nothing.

8. Putting rows in: INSERT and RETURNING

INSERT INTO tasks (title, notes, priority, due_at)
VALUES ('write the SQL primer', '', 'high', '2026-09-01 09:00:00+00')
RETURNING *;

Read it as three parts: which table and which columns you are filling; the values, in the same order; and what you want handed back.

Columns you leave out get their DEFAULT (or NULL if there is no default and the column allows it). That is why the insert above never mentions id, created_at, updated_at, status or version — the schema fills all five.

RETURNING is the piece to internalise. In most databases, inserting and then finding out what id you got takes a second query. Postgres lets the insert hand the finished row straight back, in the same round trip, from the same snapshot. taskd uses it everywhere: Chapter 7’s very first query is INSERT INTO tasks ... RETURNING *, and Chapter 8’s UpdateTask ends with RETURNING * too.

RETURNING * means every column. RETURNING id, created_at, name, email, activated, version means those six — and Chapter 10 uses exactly that list on CreateUser so that the handler physically cannot leak password_hash, even by accident.

Run this

psql’s \x on switches to one-field-per-line display, which is easier to read for a wide row.

\x on
INSERT INTO tasks (title, notes, priority, due_at)
VALUES ('another one', 'with RETURNING', 'medium', NULL)
RETURNING *;
\x off

Expanded display is on.
-[ RECORD 1 ]----------------------------
id         | 1
created_at | 2026-08-15 19:03:45.20259+00
updated_at | 2026-08-15 19:03:45.20259+00
title      | write the SQL primer
notes      | 
status     | open
priority   | high
due_at     | 2026-09-01 09:00:00+00
version    | 1

INSERT 0 1
Expanded display is off.

Your id, created_at and updated_at will differ from the ones above — the transcript is from one real run, and both the clock and the id counter have moved since. INSERT 0 1 is Postgres’ summary line: one row inserted.

9. Getting rows out: SELECT, WHERE, ORDER BY, LIMIT

SELECT has a fixed skeleton, and taskd’s biggest query — the one in Chapter 9 — is this skeleton with the blanks filled in:

  SELECT   which columns
  FROM     which table
  WHERE    which rows          (filter)
  ORDER BY in what order       (sort)
  LIMIT    how many            (page size)
  OFFSET   skipping how many   (page number)

WHERE takes a condition. The operators taskd uses: =, <> (not equal), >, <, IS NULL, IS NOT NULL, AND, OR, and ILIKE (case-insensitive pattern match, where % means “any run of characters”). Chapter 9’s search filter is title ILIKE '%' || search || '%', and || is string concatenation, so a search for tax becomes the pattern %tax%.

ORDER BY takes columns and a direction, ASC (default) or DESC. Rows containing NULL sort last only if you say NULLS LAST — worth knowing because Chapter 9 sorts by due_at, and tasks without a due date should not lead the list.

LIMIT and OFFSET are how pagination works: page 3 with 20 per page is LIMIT 20 OFFSET 40. Chapter 9 computes exactly that in Go: func (f Filters) Offset() int32 { return int32((f.Page - 1) * f.PageSize) }.

One rule that looks like decoration and is not: always end ORDER BY with a tiebreaker on a unique column. Chapter 9’s query ends ..., id ASC. Without it, rows that tie on the main sort key can come back in a different order on each query, and a row can appear on page 1 and page 2. Users report that as “sometimes an item shows up twice”, and you chase it for a week.

Run this

SELECT id, title, priority FROM tasks WHERE status = 'open';

 id |        title         | priority 
----+----------------------+----------
  1 | write the SQL primer | high
  2 | buy milk             | low
  3 | file the tax return  | high
  5 | water the plants     | none
(4 rows)

SELECT id, title FROM tasks
WHERE status = 'open' AND title ILIKE '%TAX%';

 id |        title        
----+---------------------
  3 | file the tax return
(1 row)

Note the capitals in '%TAX%' matching lowercase tax — that is the I in ILIKE.

SELECT id, title, due_at FROM tasks ORDER BY due_at ASC NULLS LAST, id ASC;

 id |        title         |         due_at         
----+----------------------+------------------------
  1 | write the SQL primer | 2026-09-01 09:00:00+00
  3 | file the tax return  | 2026-09-30 00:00:00+00
  2 | buy milk             | 
  4 | renew passport       | 
  5 | water the plants     | 
  6 | cancel the gym       | 
(6 rows)

The four undated tasks sit at the bottom, ordered among themselves by id — that is the tiebreaker doing its job.

SELECT id, title FROM tasks ORDER BY id ASC LIMIT 2 OFFSET 2;

 id |        title        
----+---------------------
  3 | file the tax return
  4 | renew passport
(2 rows)

That is page 2 with a page size of 2.

10. Counting, and the window-function trick

count(*) counts rows. Chapter 12 adds this query for Chapter 17’s quota check:

-- name: CountActiveTasks :one
SELECT count(*) FROM tasks WHERE user_id = $1 AND status <> 'archived';

Now the trick. A list endpoint needs both a page of rows and the total number of matching rows, so the client can render “page 2 of 9”. Two queries would mean two round trips, and the count could change between them. Instead, Chapter 9 attaches the total to every row of the page:

count(*) OVER() AS total_count

OVER() turns count(*) into a window function: instead of collapsing the result into one row, it computes the count across the whole filtered result set and hands it back as an extra column on each row. One query, one snapshot, count and page guaranteed consistent. The Go side then reads it off any row.

Run this

SELECT count(*) FROM tasks WHERE status <> 'archived';

SELECT id, title, count(*) OVER() AS total_count
FROM tasks WHERE status = 'open' ORDER BY id LIMIT 2;

 count 
-------
     5
(1 row)

 id |        title         | total_count 
----+----------------------+-------------
  1 | write the SQL primer |           4
  2 | buy milk             |           4
(2 rows)

Two rows came back because of the LIMIT, but each carries total_count = 4 — the number of open tasks before the limit. That single column is what fills the metadata block in every taskd list response.

11. Changing and removing rows

UPDATE tasks
SET status = 'done', version = version + 1, updated_at = now()
WHERE id = 2 AND version = 1
RETURNING id, title, status, version;

UPDATE names the table, SET lists the assignments, WHERE chooses the rows. The right-hand side of a SET can read the current value — version = version + 1 increments a counter without a read-then-write round trip.

That AND version = 1 is taskd’s optimistic lock, and it is worth understanding now because Chapter 8 (CRUD done properly) builds a whole error path on it. Two people load the same task, both edit the title, both save. Without the version check the second save silently erases the first — a lost update. With it, the second UPDATE matches zero rows (the version moved on), sqlc reports pgx.ErrNoRows, and the handler returns HTTP 409 Conflict. No locks are held, no one waits; the database’s atomicity does all the work.

DELETE is the same shape without SET:

DELETE FROM tasks WHERE id = 6;

Run this

UPDATE tasks
SET status = 'done', version = version + 1, updated_at = now()
WHERE id = 2 AND version = 1
RETURNING id, title, status, version;

 id |  title   | status | version 
----+----------+--------+---------
  2 | buy milk | done   |       2
(1 row)

UPDATE 1

Now run the exact same statement a second time:

 id | title | status | version 
----+-------+--------+---------
(0 rows)

UPDATE 0

Zero rows. The row’s version is 2 now, so version = 1 matches nothing. That empty result is the conflict signal — an HTTP 409 in Chapter 8. Finish with:

DELETE FROM tasks WHERE id = 6;
DELETE FROM tasks WHERE id = 6;

DELETE 1, then DELETE 0. Chapter 8’s DeleteTask query is declared :execrows for exactly this reason: the affected-row count is how the handler tells “deleted” (1) from “never existed” (0), which becomes 204 or 404.

12. A second table, and foreign keys

Now users, exactly as Chapter 10 creates it:

-- migrations/000002_create_users.up.sql — the real thing
CREATE EXTENSION IF NOT EXISTS citext;

CREATE TABLE users (
    id            bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    created_at    timestamptz NOT NULL DEFAULT now(),
    name          text        NOT NULL,
    email         citext      NOT NULL UNIQUE,   -- the constraint IS the dedupe logic
    password_hash bytea       NOT NULL,          -- bcrypt output: bytes, never text
    activated     boolean     NOT NULL DEFAULT true, -- flipped to false in ch. 21
    version       integer     NOT NULL DEFAULT 1      -- same optimistic lock as tasks
);

Insert two users, then try to insert a third with an email that differs only in capitalisation ('\x00' is a placeholder byte value standing in for a real bcrypt hash):

INSERT INTO users (name, email, password_hash)
VALUES ('Alice', 'alice@example.com', '\x00') RETURNING id, name, email, activated;

INSERT INTO users (name, email, password_hash)
VALUES ('Bob', 'BOB@Example.com', '\x00') RETURNING id, name, email;

INSERT INTO users (name, email, password_hash)
VALUES ('Bob again', 'bob@example.com', '\x00');

 id | name  |       email       | activated 
----+-------+-------------------+-----------
  1 | Alice | alice@example.com | t
(1 row)

 id | name |      email      
----+------+-----------------
  2 | Bob  | BOB@Example.com
(1 row)

ERROR:  duplicate key value violates unique constraint "users_email_key"
DETAIL:  Key (email)=(bob@example.com) already exists.

Two things happened there. citext stored BOB@Example.com with its original capitals but compares it case-insensitively, so the third insert collided. And the collision reported as duplicate key value violates unique constraint — Postgres error code 23505, the one Chapter 10’s handler catches with errors.As and turns into “a user with this email address already exists”.

Foreign keys

A foreign key is a column that must contain a value present in another table’s primary key. It is the database enforcing “every task belongs to a real user”. Chapter 12 adds it:

-- migrations/000004_add_user_id_to_tasks.up.sql
-- up: dev-grade — production would backfill instead of truncate.
TRUNCATE tasks;
ALTER TABLE tasks
    ADD COLUMN user_id bigint NOT NULL REFERENCES users ON DELETE CASCADE;
CREATE INDEX idx_tasks_user_id ON tasks (user_id);

Try it without the TRUNCATE first, so you feel why it is there:

ALTER TABLE tasks
    ADD COLUMN user_id bigint NOT NULL REFERENCES users ON DELETE CASCADE;

ERROR:  column "user_id" of relation "tasks" contains null values

You asked for a column that can never be NULL, on a table that already has rows, without saying what those rows should contain. In production the answer is the three-step dance — add the column nullable, backfill it, then set NOT NULL. In development, with throwaway rows, Chapter 12 takes the honest shortcut and says so. Run the real migration:

TRUNCATE tasks;
ALTER TABLE tasks
    ADD COLUMN user_id bigint NOT NULL REFERENCES users ON DELETE CASCADE;
CREATE INDEX idx_tasks_user_id ON tasks (user_id);

TRUNCATE empties a table completely, faster than DELETE and with no WHERE. Chapter 20 (Testing what matters) uses TRUNCATE ... RESTART IDENTITY CASCADE between tests for the same reason: a clean table in one statement.

Run this

INSERT INTO tasks (user_id, title, priority) VALUES
  (1, 'write the SQL primer', 'high'),
  (1, 'water the plants',     'none'),
  (2, 'file the tax return',  'high');

INSERT INTO tasks (user_id, title) VALUES (999, 'ghost task');

INSERT 0 3
ERROR:  insert or update on table "tasks" violates foreign key constraint "tasks_user_id_fkey"
DETAIL:  Key (user_id)=(999) is not present in table "users".

There is no user 999, so there can be no task belonging to user 999. Orphan rows are now impossible — not “unlikely if everyone is careful”, impossible.

ON DELETE CASCADE

ON DELETE CASCADE answers the question “what happens to the children when the parent is deleted?” The answer taskd chooses: delete them too, in the same operation.

SELECT count(*) AS bobs_tasks FROM tasks WHERE user_id = 2;
DELETE FROM users WHERE id = 2;
SELECT count(*) AS bobs_tasks FROM tasks WHERE user_id = 2;

 bobs_tasks 
------------
          1
(1 row)

DELETE 1
 bobs_tasks 
------------
          0
(1 row)

Deleting Bob deleted Bob’s task. Nobody wrote code to do that.

13. JOIN

A join answers one question using two tables at once. This book contains exactly one, in Chapter 11 (Stateful tokens), and it is the whole of taskd’s authentication:

-- name: GetUserForToken :one
SELECT u.id, u.created_at, u.name, u.email, u.activated, u.version
FROM users u
INNER JOIN tokens t ON t.user_id = u.id
WHERE t.hash = $1 AND t.scope = $2 AND t.expiry > now();

Line by line:

• FROM users u — start with users, and call it u for short. That short name is an alias.
• INNER JOIN tokens t ON t.user_id = u.id — pair each user with each of their tokens. INNER means: keep a pair only if both sides exist. ON states the pairing rule, which here is the foreign key we just created.
• WHERE ... — of those pairs, keep the one whose token hash matches, whose scope is right, and whose expiry is still in the future.
• SELECT u.... — return columns from the users side only. password_hash is deliberately absent, so the user object the middleware carries around physically cannot leak it.

Two design points hide in there. The expiry check lives in SQL, so no Go code path can forget it. And the whole “who is this request from?” question costs one query.

Run this

First create the tokens table, exactly as Chapter 11 does, and put a token in it. sha256(...) is a real Postgres function; here it stands in for what Go computes in Chapter 11.

CREATE TABLE tokens (
    hash    bytea PRIMARY KEY,
    user_id bigint NOT NULL REFERENCES users ON DELETE CASCADE,
    expiry  timestamptz NOT NULL,
    scope   text NOT NULL
);

INSERT INTO tokens (hash, user_id, expiry, scope)
VALUES (sha256('pretend-this-is-a-real-token'::bytea), 1,
        now() + interval '24 hours', 'authentication');

Now run the book’s authentication query with the values filled in:

SELECT u.id, u.name, u.email
FROM users u
INNER JOIN tokens t ON t.user_id = u.id
WHERE t.hash = sha256('pretend-this-is-a-real-token'::bytea)
  AND t.scope = 'authentication'
  AND t.expiry > now();

 id | name  |       email       
----+-------+-------------------
  1 | Alice | alice@example.com
(1 row)

That is a logged-in user, resolved from a bearer token, in one round trip. Change one character of the token string and you get zero rows — which is a 401.

now() + interval '24 hours' is date arithmetic; Chapter 21 uses the same shape backwards in DELETE FROM stripe_events WHERE received_at < now() - interval '30 days'.

14. Indexes, and what EXPLAIN shows

Without an index, answering WHERE user_id = 42 means reading every row in the table and discarding the ones that do not match. That is a sequential scan, and its cost grows in a straight line with every signup.

An index is a separate, sorted structure the database maintains alongside the table, mapping column values to row locations — like the index at the back of a book. Looking up a value in it is fast no matter how big the table is. The trade is that every INSERT, UPDATE and DELETE must also update the index, and the index takes disk space. You add indexes for the queries you actually run, not for every column.

Chapter 12 adds CREATE INDEX idx_tasks_user_id ON tasks (user_id); in the same migration as the foreign key, and is blunt about why: “every single query from now on filters by user_id; without the index each one is a sequential scan that gets linearly worse with every signup.” Chapter 21 adds a second one, idx_tokens_user_id, after a review finding — Postgres does not automatically index foreign key columns, and the activation and password-reset flows delete by user and scope constantly.

EXPLAIN shows you the plan Postgres intends to use, without running the query. It is how you find out whether your index is being used, and it is what Chapter 9’s pitfall means by “know which regime you’re in — EXPLAIN ANALYZE is how”.

Run this

Two tasks is not enough data for the planner to care. Make 50,000. generate_series is a Postgres helper for producing test data; the book never uses it.

INSERT INTO users (name, email, password_hash)
SELECT 'user ' || n, 'user' || n || '@example.com', '\x00'
FROM generate_series(1, 500) AS n;

INSERT INTO tasks (user_id, title)
SELECT u.id, 'task ' || n
FROM users u, generate_series(1, 100) AS n;

ANALYZE tasks;
SELECT count(*) FROM tasks;

INSERT 0 500
INSERT 0 50100
ANALYZE
 count 
-------
 50102
(1 row)

ANALYZE tells Postgres to re-measure the table so its planner has current statistics. Now:

EXPLAIN SELECT id, title FROM tasks WHERE user_id = 42;

                                    QUERY PLAN                                    
----------------------------------------------------------------------------------
 Bitmap Heap Scan on tasks  (cost=5.07..263.43 rows=100 width=15)
   Recheck Cond: (user_id = 42)
   ->  Bitmap Index Scan on idx_tasks_user_id  (cost=0.00..5.04 rows=100 width=0)
         Index Cond: (user_id = 42)

Read it inside-out. The innermost step, Bitmap Index Scan on idx_tasks_user_id, uses the index to find where the matching rows live; the outer step fetches them. rows=100 is the planner’s estimate of how many rows come back. cost=5.07..263.43 is an arbitrary unit — useful for comparing two plans, meaningless on its own.

Now take the index away and ask again:

DROP INDEX idx_tasks_user_id;
EXPLAIN SELECT id, title FROM tasks WHERE user_id = 42;

        QUERY PLAN         
-----------------------------------------------------------
 Seq Scan on tasks
   Filter: (user_id = 42)

Seq Scan with a Filter: read all 50,102 rows, keep 100. The estimated cost went from 263 to 1196. Put it back:

CREATE INDEX idx_tasks_user_id ON tasks (user_id);

15. Transactions, atomicity, and rollback

A transaction is a group of statements that either all happen or none do. You open one with BEGIN, and end it with COMMIT (make it permanent) or ROLLBACK (pretend it never happened).

The four properties are known by the acronym ACID, and each is one sentence:

The one to actually internalise is atomicity, because this book leans on it constantly without naming it. A single SQL statement is already atomic. That fact is what makes three of the book’s cleverest moves work:

• Chapter 8’s optimistic lock: UPDATE ... WHERE id = $1 AND version = $7 either matches and bumps the version, or matches nothing. There is no in-between for a competitor to slip into.
• Chapter 10’s registration: the UNIQUE constraint decides duplicates, with no check-then-insert window.
• Chapter 15’s INSERT ... ON CONFLICT DO NOTHING as a webhook idempotency ledger — Chapter 15 calls it “atomic idempotency in one statement”.

Run this

BEGIN;
UPDATE tasks SET title = 'a title I will regret' WHERE id = 1;
SELECT id, title FROM tasks WHERE id = 1;
ROLLBACK;
SELECT id, title FROM tasks WHERE id = 1;

BEGIN
UPDATE 1
 id |         title         
----+-----------------------
  1 | a title I will regret
(1 row)

ROLLBACK
 id |        title         
----+----------------------
  1 | write the SQL primer
(1 row)

Inside the transaction, your own session sees the change. After ROLLBACK, it never happened — and no other session ever saw it. This is also the safest way to try a dangerous UPDATE: wrap it in BEGIN, look at the row count, then COMMIT or ROLLBACK accordingly.

16. Connections, pools, and reading a DSN

A connection is an open network conversation between your program and the database: a TCP connection, an authentication handshake, and — on the Postgres side — a whole operating-system process forked to serve it. It is expensive to create and cheap to keep.

A web server cannot open one per request. Chapter 4 gives every request its own goroutine, so dozens of handlers may want the database at the same instant, and paying the handshake cost on each would dominate your response time.

Why 25 and not 200? Because Postgres’ max_connections defaults to 100, that budget is shared by every instance of your app plus psql, migrations and backups, and each connection costs a process. Chapter 6’s rule: start at 25 per instance, then let the pool metrics exported in Chapter 18 (Prometheus) tell you the truth.

Reading a DSN

A DSN (data source name) is the whole address of a database squeezed into one string. This is the one Chapter 5 puts in .envrc:

postgres://taskd:pa55word@localhost:5432/taskd?sslmode=disable
└──┬───┘   └─┬─┘ └───┬───┘ └───┬───┘ └─┬┘ └─┬─┘ └──────┬──────┘
scheme     user  password    host    port  database  options

Read it once, left to right; you will be reading these for the rest of your career.

Run this

SHOW max_connections;
SELECT count(*) AS open_connections FROM pg_stat_activity WHERE datname = 'taskd';

 max_connections 
-----------------
 100
(1 row)

 open_connections 
------------------
                1
(1 row)

One connection: the psql session you are typing in. From Chapter 6 onward this number jumps, because the pool opens several at boot and holds them.

17. Migrations: schema changes, ordered and versioned

Your schema changes over a project’s life, and those changes must happen identically on your laptop, your teammate’s, CI and production. A migration is a numbered SQL file that makes one such change, paired with a file that undoes it.

You have already read six of taskd’s seven:

migrations/
  000001_create_tasks.up.sql          §3   CREATE TABLE tasks
  000002_create_users.up.sql          §12  CREATE TABLE users, citext
  000003_create_tokens.up.sql         §13  CREATE TABLE tokens
  000004_add_user_id_to_tasks.up.sql  §12  the FK and idx_tasks_user_id
  000005_billing.up.sql               Ch15 subscriptions, stripe_events
  000006_activation.up.sql            Ch21 activated DEFAULT false, idx_tokens_user_id
  000007_pending_email.up.sql         Ch22 users.pending_email

Order is the point. 000004 adds a foreign key pointing at users, so 000002 must have run first. Numbering is what makes “run everything that hasn’t run yet” a safe, repeatable command. The tool taskd uses is golang-migrate; it records applied versions in a bookkeeping table called schema_migrations (two columns: version and dirty) which appears in \dt from Chapter 5 onward. Leave it alone.

Three rules, all from Chapter 5’s pitfalls:

1. An applied migration is immutable history. Once it has run anywhere — a teammate’s machine, CI, production — editing it makes two databases claim the same version while differing. Wrong? Write a new migration that fixes it.
2. Down migrations are for development. Rolling schema back in production usually loses data; real production rollbacks are roll-forwards. Write the down files anyway — they make local iteration pleasant.
3. If a migration fails halfway, migrate marks the database “dirty” and refuses to continue until a human looks. In development, docker compose down -v and re-up is often the honest reset.

There is a fourth rule that belongs to Chapter 7 and will bite you sooner: never run migrations without regenerating. sqlc reads migrations/ as its schema source, so a schema change that isn’t followed by sqlc generate leaves your Go compiled against yesterday’s tables. Chapter 7’s muscle-memory fix: make db/migrations/up sqlc.

Run this

Nothing new to type — your psql session has been a hand-run migration all along. Instead, look at what you built:

\dt

You should see tasks, tokens and users. That is migrations 000001 through 000004, applied by hand, in order.

18. One more thing: $1 and why it is not string-pasting

Every query in this book has numbers in it: WHERE id = $1 AND user_id = $2. Those are bind parameters — placeholders. You send the query text and the values as two separate things, and the database never confuses one for the other.

The alternative — gluing user input into the query text — is how SQL injection happens. If a search box’s contents get pasted into a statement, a user who types '; DROP TABLE tasks; -- has just sent you a second statement. With $1, that text is a value containing punctuation, and nothing more.

One limitation to know now, because Chapter 9 hits it head-on: a placeholder can stand in for a value, never for a column or table name. ORDER BY $1 is not legal SQL. Chapter 9 works around it with a CASE ladder, and checks the requested sort against a whitelist in Go first. Its rule, worth copying verbatim: never interpolate user input into an ORDER BY. Ever.

You will not type $1 by hand often. From Chapter 7 onward, sqlc reads your $1s and generates a Go struct with a typed field for each one.

The whole schema, at the end of the book

Every table, every relationship, as Appendix C has it. Arrows point from the foreign key to the primary key it references.

                 ┌────────────────────────────────────────┐
                 │ users                                  │
                 │   id                 bigint   PK       │
                 │   created_at         timestamptz       │
                 │   name               text              │
                 │   email              citext   UNIQUE   │
                 │   password_hash      bytea             │
                 │   activated          boolean           │
                 │   stripe_customer_id text     UNIQUE   │
                 │   pending_email      citext   (nullable)│
                 │   version            integer           │
                 └────────────────────────────────────────┘
                       ▲              ▲              ▲
                       │              │              │
          user_id ─────┘   user_id ───┘   user_id ───┘
       ON DELETE CASCADE  ON DELETE CASCADE  ON DELETE CASCADE
  ┌──────────────────┐ ┌──────────────────┐ ┌───────────────────────┐
  │ tasks            │ │ tokens           │ │ subscriptions         │
  │  id       PK     │ │  hash    PK bytea│ │  user_id      PK      │
  │  user_id  FK     │ │  user_id FK      │ │  stripe_subscription_ │
  │  created_at      │ │  expiry  tstz    │ │        id text UNIQUE │
  │  updated_at      │ │  scope   text    │ │  tier         text    │
  │  title    text   │ └──────────────────┘ │  status       text    │
  │  notes    text   │  idx_tokens_user_id  │  current_period_end   │
  │  status   CHECK  │                      │  updated_at           │
  │  priority CHECK  │                      └───────────────────────┘
  │  due_at   (null) │
  │  version  integer│      ┌──────────────────────────┐
  └──────────────────┘      │ stripe_events            │  no foreign key:
   idx_tasks_user_id        │  id          text PK     │  a ledger of
                            │  received_at timestamptz │  webhook ids
                            └──────────────────────────┘

Walking it:

1. users is the root. Every other table with a person in it points here.
2. tasks.user_id arrives in Chapter 12 and makes taskd multi-tenant. Its index, idx_tasks_user_id, exists because every query from that chapter on filters by it.
3. tokens.user_id arrives in Chapter 11. The primary key is the token’s SHA-256 hash, not an id, because the hash is the token’s identity. idx_tokens_user_id arrives in Chapter 21.
4. subscriptions.user_id is primary key and foreign key at once — that is Chapter 15 spelling “one subscription per user” as a constraint rather than a comment.
5. stripe_events stands alone. It records which Stripe webhook ids have already been processed, so a redelivered event is a no-op (Chapter 16).
6. Three cascades, all pointing at users. Deleting a user removes their tasks, tokens and subscription in one statement — which is what Chapter 22’s account-deletion flow relies on.

Common mistakes

Check yourself

1. notes is text NOT NULL DEFAULT '' but due_at is plain timestamptz. What is the difference in what those two columns can say?
2. You run SELECT * FROM tasks WHERE due_at = NULL; and get zero rows, though you know four tasks have no due date. Why?
3. UPDATE tasks SET status='done', version=version+1 WHERE id=7 AND version=3 returns UPDATE 0. Give two different explanations, and say how the handler in Chapter 8 tells them apart.
4. Why does Chapter 9 end its ORDER BY with id ASC when it has already sorted by created_at?
5. What does count(*) OVER() give you that a separate SELECT count(*) query does not?
6. idx_tasks_user_id indexes tasks(user_id). Name one query it makes fast and one cost it imposes.
7. A user is deleted. Without any Go code running, what else disappears, and what mechanism does it?
8. taskd never writes BEGIN or COMMIT. Is that a bug? Defend your answer in two sentences.

FAQ

Do I need to memorise this? No. You need to recognise it. When Chapter 9’s query appears with count(*) OVER(), ILIKE, NULLS LAST and a CASE ladder in it, you should feel “I know four of these five things” rather than “this is hieroglyphics”. Come back to the relevant section instead of re-reading the whole warm-up.

Why write SQL at all, when there are libraries that generate it? Chapter 1 argues this properly, and Chapter 7 makes it concrete. The short version: with an ORM you review Go and the database receives SQL you have never seen. taskd writes plain SQL and uses sqlc to generate the tedious part — the scanning of rows into structs — so mismatches become compile errors instead of runtime surprises.

Why is so much validation in the schema rather than in Go? Because a schema rule cannot be bypassed and a Go rule can. A CHECK constraint rejects status = 'banana' no matter which handler, background job, migration or psql session tries it. Your Go validation still exists — it produces friendly error messages — but the database is the thing that is actually load-bearing.

Is Postgres overkill for a task manager? For the first hundred users, yes, and so is almost everything else in this book. The reason to start here is that the alternative is a rewrite at exactly the moment you cannot afford one. Postgres runs happily in a container on your laptop and scales to workloads far past anything you will build in these 27 chapters.

Should I learn GROUP BY, subqueries and window functions properly? Eventually, yes — they are the next things you will need, and they are genuinely useful. But this book does not use them, and a primer full of constructs the codebase never contains is a primer you paid for and did not use. Learn them when a real query demands them.

Everything I typed is gone when I delete the container. Isn’t that wasteful? That is the point. This database was scratch paper. Chapter 5 builds the real one with Docker Compose, a named volume so data survives restarts, and versioned migrations so the schema is reproducible from Git.

Where we are

You can read every .sql file in this book. You have built four of taskd’s five tables by hand, watched Postgres refuse five different kinds of bad data, seen an index change a query plan, and rolled back a transaction.

Clean up:

docker rm -f sql-primer

That deletes the container and everything in it. Chapter 5 starts fresh.

Come back here when

For your notes

• A database is not a file with extra steps. It exists because many things read and write at once, and because rules stored with the data cannot be skipped by the next code path someone writes.
• NULL means unknown, and unknown is not equal to unknown. IS NULL, never = NULL.
• A constraint is validation that no code path can bypass. UNIQUE beats check-then-insert because it has no window between the check and the insert.
• RETURNING turns a write into a read. Every write in this book uses it, and that is why taskd never needs a follow-up SELECT to learn the id it just created.
• One SQL statement is atomic. That single fact is what makes taskd’s optimistic locking, its duplicate-email handling and its webhook idempotency ledger correct without a single explicit transaction.

Chapter 1 — Introduction: what we’re building and why this shape

This chapter writes no code. It makes four decisions instead, out loud, with the rejected options written down beside the chosen ones: how requests find code, how code talks to the database, which library speaks to PostgreSQL, and whether this is one program or many. Those four are cheap today and expensive in six months, so we make them now, while nothing exists to break.

What you’ll be able to do by the end

• Say in plain words what taskd is, and translate every phrase in its feature list into English.
• Name the four decisions every web project makes before its first line, with one reason for each of taskd’s answers.
• Apply one reusable test — could you rip it out in an afternoon? — to any library, forever.
• Read the system diagram and trace one request through it, naming what each box does.
• Prove your machine has the tools the next twenty-six chapters need.

Time: ~30 minutes reading, ~10 minutes typing.

You need before starting: the warm-up chapter Before you begin, with its thirteen-line checklist ticked. Nothing from a previous chapter’s code, because there is none yet. Prove your machine is ready:

go version

You should get a line beginning go version go1.24 or higher. If it says command not found, stop and finish Before you begin; every remaining chapter depends on it.

1. The problem, in plain words

You are going to build a product that other programs pay to talk to. Not a demo. A service with users, passwords, money, limits, and a way to find out what it is doing at three in the morning.

Four questions come before any of that. They sound like technical trivia. They are the questions that decide how much of this codebase you can still change a year from now.

1. When a request arrives, what decides which of your functions answers it?
2. How does your Go code ask the database a question, and what happens when the question is wrong?
3. Which library actually speaks to PostgreSQL over the network?
4. Is this one program, or several?

A tutorial answers these with whichever tool is most popular this month. A team answers them by asking what each choice costs to undo.

That gives one test, used four times in this chapter and for the rest of your working life.

The book calls this the Nadh test, after Kailash Nadh, a CTO whose teams run enormous systems on deliberately small toolkits (the preface introduces him). You never need to have read a word of his to use it. It is one question.

2. New words in this chapter

These are the words the argument needs. The product vocabulary — CRUD, webhook, quota, distroless and the rest — is defined in section 3’s table, where you first meet each one.

• API — a way for one program to ask another to do something, over a fixed list of requests with fixed shapes. A drive-through menu.
• endpoint — one address-plus-method your API answers, e.g. POST /v1/tasks. One menu item.
• SaaS — software you rent by the month over the internet instead of buying a copy.
• versioned API / /v1 — a version number in every address, so a future incompatible /v2 can exist without breaking today’s callers.
• binary — the single runnable file the Go compiler produces. Nobody needs Go installed to run it.
• standard library — the code that ships with Go and needs no download. In Go, the web server is part of it.
• framework — a library that supplies your program’s overall structure and asks you to fill in the blanks. You write code inside its shape.
• router — the code that matches an incoming address like /v1/tasks/48 to the function that should answer it. The mailroom sorting frame.
• handler — that function. Chapter 2 (The skeleton: a server that answers) writes the first one.
• middleware — a function that wraps a handler, doing something before and after it, and hands back a handler again — so they stack. Chapter 4 (A server that dies well) builds ours.
• JSON — the labelled text format data travels in on the web: {"title": "buy milk", "done": false}. Taught in How the web actually works.
• ORM — a library that writes your database queries for you, from code objects.
• query builder — the middle option: you assemble SQL by calling Go methods rather than writing it as text.
• driver — the library that speaks a database’s network language. The phone line to Postgres.
• container / image — an image is a sealed package of a program plus everything it needs to run; a container is one running copy of an image. Chapter 25 (Docker) builds ours.
• connection pool — a few already-open database connections the server keeps and reuses, because opening one costs milliseconds. Chapter 6 (Connecting with pgx/v5) sizes ours.
• code generation — a tool that reads one file and writes another file of real source code before you compile. What it writes is ordinary code you can open and read.
• monolith — one program containing all the features, deployed as one unit. Microservices is the opposite: many small programs talking over a network.
• modular monolith — one program, but with internal walls: packages that do not reach into each other’s business.
• lock-in — not being able to leave a dependency without rewriting a large part of your program.

3. The goal

By the last chapter you will have one file. You can copy it to a server and run it, and it is a business: it keeps each user’s task list and lets them add, change, search and delete over the internet; it knows who is calling and refuses to show one person another’s tasks; it sells three subscription plans through Stripe and enforces what each may do; it survives load and abuse; it reports its own health in a format monitoring tools read; and it rebuilds and redeploys itself when you push code.

Here is the same list in the industry’s own words. Read the bullets, then the table under them.

By the last chapter you will have a single Go binary, taskd, that:

• serves a versioned JSON API (/v1/...) for tasks — create, read, update, delete, list with filtering, full-text-ish search, sorting and pagination;
• registers users, hashes passwords properly, and authenticates requests with stateful bearer tokens (and can defend, in an interview, why it didn’t use JWTs);
• is a real SaaS: three tiers (Free, Pro, Business) sold through Stripe Checkout, kept in sync by webhooks, enforced by quotas and feature gates in the API;
• caches hot reads in DragonflyDB with O(1) invalidation, and rate-limits per plan using the same store;
• exposes Prometheus metrics (RED metrics per route, DB pool stats) and emits structured JSON logs with log/slog;
• ships as a ~15 MB distroless Docker image, with a Compose stack for the whole system and a GitHub Actions pipeline that lints, tests, vets SQL, scans for vulnerable dependencies, builds the image and pushes it to a registry;
• shuts down gracefully, survives panics, refuses oversized bodies, and does a dozen other small production-grade things that separate demos from services.

The decoder. You are not expected to know any of these yet.

4. The thinking: choosing the shape before writing a line

Every project starts with four decisions that are expensive to reverse. Let’s make them consciously.

4.1 Decision 1 — Framework or stdlib-plus-router?

What is being decided. When a request for GET /v1/tasks/48 arrives, something must read that address and call the right function.

The paths: (a) a full framework (Gin, Echo, Fiber), (b) pure net/http, © net/http plus a tiny router.

Frameworks buy you speed on day one and cost you on day two hundred: their context types leak into every function signature, middleware ecosystems lock you in, and when something misbehaves you’re debugging their abstractions.

That is the whole argument, and it is invisible until you see it. The same handler — “give me the task whose id is in the URL” — three ways:

// illustration only, not a taskd file — the standard library, Go 1.22+
func showTask(w http.ResponseWriter, r *http.Request) {
    id := r.PathValue("id")
    fmt.Fprintf(w, "task %s", id)
}

// illustration only, not a taskd file — chi
func showTask(w http.ResponseWriter, r *http.Request) {
    id := chi.URLParam(r, "id")
    fmt.Fprintf(w, "task %s", id)
}

// illustration only, not a taskd file — a framework with its own context type
func showTask(c *gin.Context) {
    id := c.Param("id")
    c.String(http.StatusOK, "task %s", id)
}

What this code says, line by line

• A signature is a function’s first line: its name and the types it accepts. The first two are identical — func(http.ResponseWriter, *http.Request) — and both types belong to Go itself. w is where you write the reply; r is the request that arrived.
• The third names *gin.Context. The function no longer accepts Go’s request type; it accepts the framework’s.
• r.PathValue("id") and chi.URLParam(r, "id") each pull 48 out of /v1/tasks/{id} — a path parameter, a named hole in a route pattern. The difference between them is one call, in one place.

Now the question that matters: which of these could you paste into a different Go project? The first two, unchanged. The third works only inside Gin — and so does every function that calls it and every test that exercises it. Forty handlers later, the framework is not a dependency; it is the shape of your program.

Pure net/http (with Go 1.22’s improved ServeMux) is genuinely viable now — method matching and path params exist.

We still pick chi: it is net/http (every handler is a standard http.HandlerFunc), adds sub-routers, middleware groups and route patterns we’ll later need for Prometheus labels, and weighs almost nothing. This is the Nadh test: could you rip it out in an afternoon? With chi, yes.

4.2 Decision 2 — ORM, query builder, or SQL?

What is being decided. Your Go code holds a Task struct — a labelled box with an id, a title, a status. Your database holds a row of columns. Something must carry values between them and produce the SQL.

The heading names three ways, and the middle one deserves a sentence before we set it aside. A query builder lets you assemble SQL by calling Go methods — .Select(...), .Where(...) — instead of writing it as text. It carries the ORM’s problem in smaller measure: the query that finally reaches Postgres is still assembled by a library, so it is still something you read back rather than something you wrote. The argument below is therefore about the two ends.

GORM-style ORMs generate SQL you didn’t write and can’t easily predict; at scale you end up fighting them.

// illustration only, not a taskd file — an ORM
db.Where("status = ?", "done").Order("created_at desc").Limit(20).Find(&tasks)

Which query did that send? You find out by switching on query logging and reading it back, and the answer can change when you upgrade the library. When it is slow, the thing you must optimise is a thing you did not write.

Hand-rolled database/sql scanning is honest but produces mountains of rows.Scan(&a, &b, &c) boilerplate where one misordered field is a runtime bug:

// illustration only, not a taskd file — writing it all by hand
rows, err := db.Query("SELECT id, created_at, title, status, version FROM tasks")
if err != nil {
    return nil, err
}
defer rows.Close()

var tasks []Task
for rows.Next() {
    var t Task
    err := rows.Scan(&t.ID, &t.CreatedAt, &t.Title, &t.Status, &t.Version)
    if err != nil {
        return nil, err
    }
    tasks = append(tasks, t)
}

What this code says, line by line

• db.Query(...) sends the SQL text and returns a cursor over the results; for rows.Next() steps through one row at a time.
• rows.Scan(&t.ID, ...) copies the row’s columns into the struct’s fields, matched by position, not by name. The & means “the address of this field”, which is how Scan writes into it rather than into a copy.
• There is the bug. title and status are both text. Swap those two arguments and the code compiles, runs, and quietly files every task’s status in its title column — no error, ever. Now picture fourteen columns, edited by someone in a hurry.

sqlc is the modern sweet spot: you write real SQL in .sql files, it compiles them into typed Go functions at build time. Wrong column name? Compile error, not a 3 a.m. page. It is, in spirit, the typed descendant of the goyesql pattern Nadh’s listmonk uses — SQL lives in files, Go calls it by name.

4.3 Decision 3 — Which driver?

What is being decided. PostgreSQL is a separate program, usually on a separate machine. Talking to it means speaking its network protocol; a driver is the library that does that. Everything in 4.2 sits on top of one.

lib/pq is in maintenance mode. pgx/v5 is the actively developed driver: faster binary protocol, a built-in production-grade pool (pgxpool), native Postgres type handling. sqlc has first-class pgx/v5 support. Done.

Notice how quickly that was settled. The driver’s name appears in one setup file and a couple of error checks and nowhere else, so it is the cheapest of the four to reverse — and cheap decisions deserve short arguments.

4.4 Decision 4 — Monolith or services?

What is being decided. Tasks, users, billing and email could all live in one program, or each could be its own program on its own machine, calling the others over the network.

One binary. You are one person (or a small team) building a product, not a résumé. A modular monolith with clean internal packages can be split later, when a real bottleneck — not an architectural fantasy — demands it. Zerodha runs India’s largest broker this way. We can run a todo SaaS this way.

Everything else — cache, billing, metrics — attaches to this spine later, and each gets its own “the thinking” section when its chapter comes.

5. A picture of it

Three pictures: the decisions, the finished system, and one request moving through it.

The four decisions, with the roads not taken

 1  How do requests find code?
    ├─ Gin / Echo / Fiber ......... their Context type in every signature
    ├─ net/http alone ............. no sub-routers, no pattern for metrics
    └─ net/http + chi ... CHOSEN .. handlers stay http.HandlerFunc

 2  How does Go talk to the database?
    ├─ ORM ........................ SQL you did not write, cannot predict
    ├─ hand-written Scan .......... one misordered field = silent bug
    └─ sqlc ............. CHOSEN .. real SQL in files, compiled to typed Go

 3  Which driver?
    ├─ lib/pq ..................... maintenance mode
    └─ pgx/v5 ........... CHOSEN .. active, binary protocol, own pool

 4  One program or many?
    ├─ microservices .............. network calls where function calls were
    └─ modular monolith . CHOSEN .. one binary, internal walls, split later

The system, one screen

Every box in the finished system. Two of them are not our software.

                          ┌─────────────────────────────┐
   client ── HTTPS ──▶    │ Caddy (TLS, ch. 27)         │
                          └──────────────┬──────────────┘
                                         │ :4000
                          ┌──────────────▼──────────────┐
                          │ taskd (single Go binary)    │
                          │ chi router                  │
                          │ auth · quotas · handlers    │
                          └───┬──────────┬──────────┬───┘
                              │          │          │
                     ┌────────▼───┐ ┌────▼─────┐ ┌──▼──────────┐
                     │ PostgreSQL │ │Dragonfly │ │ Stripe API  │
                     │ (pgx/sqlc) │ │(go-redis)│ │ + webhooks  │
                     └────────────┘ └──────────┘ └─────────────┘
                              ▲
                     ┌────────┴────────┐
                     │ Prometheus ──▶ Grafana (scrapes /metrics)
                     └─────────────────┘

1. client — anything calling the API: a browser, a phone app, curl, another company’s server.
2. Caddy — an off-the-shelf web server in front, which obtains and renews the HTTPS certificate and forwards plain requests inwards; Chapter 27 (Production checklist) puts it there. TLS is the encryption that puts the S in HTTPS, so ── HTTPS ──▶ means that leg is unreadable to anyone in between. The leg into taskd is not encrypted, because it never leaves the machine.
3. :4000 — the port taskd listens on. A port is a numbered door on a machine.
4. taskd — everything this book writes, in one process: chi picks the handler, auth decides who is calling, quotas decide whether they may.
5. PostgreSQL — the permanent record, reached through pgx using SQL that sqlc turned into Go.
6. Dragonfly — DragonflyDB, an in-memory store for things that may be lost: cached reads (Chapter 13) and rate-limit counters (Chapter 14). Reached with go-redis, because Dragonfly speaks Redis’s protocol.
7. Stripe — we call it to start a checkout; it calls us back with webhooks (Chapters 15, 16).
8. Prometheus → Grafana — Prometheus visits taskd’s /metrics address every few seconds and records what it finds; Grafana draws it. Our job is only to expose the numbers (Chapter 18).

One request, end to end

A single authenticated read, once everything exists. Chapter 2 builds steps 3, 6 and 7 for one small endpoint, and you will run curl against it yourself.

  curl                Caddy              taskd (one process)        Postgres
   │                    │                        │                      │
   │ 1 HTTPS request    │                        │                      │
   ├───────────────────▶│                        │                      │
   │                    │ 2 plain HTTP to :4000  │                      │
   │                    ├───────────────────────▶│                      │
   │                    │                        │ 3 chi matches route  │
   │                    │                        │ 4 middleware: who?   │
   │                    │                        │ 5 handler queries    │
   │                    │                        ├─────────────────────▶│
   │                    │                        │◀─────────────────────┤
   │                    │                        │ 6 rows become JSON   │
   │                    │◀───────────────────────┤                      │
   │◀───────────────────┤ 7 response back out    │                      │

Everything later in this book is a layer added around that path, never a change to its shape.

6. The steps

There is no code to type. There is a machine to prove out, because Chapter 2 opens with go mod init and Chapter 5 with docker compose up, and a failure in either is far easier to diagnose now than mid-chapter.

Step 1 — Prove Go is installed and new enough

go version

This asks the Go toolchain to print its own version and the platform it was built for. It changes nothing.

What you should see: one line beginning go version go1., then a version number, then your operating system and processor — darwin/arm64 on an Apple Mac, linux/amd64 on most Linux machines. The number after go1. must be 24 or higher.

Step 2 — Prove Docker runs, and can start a container

docker compose version
docker run --rm hello-world

Compose is the part of Docker that runs several containers together from one file. docker run --rm hello-world downloads a tiny official test image, runs it, prints a message and exits; --rm deletes the stopped container afterwards, so nothing is left behind.

What you should see: a line beginning Docker Compose version v. Then possibly some download progress, followed by a paragraph containing the sentence This message shows that your installation appears to be working correctly.

Step 3 — Prove curl exists

curl --version

curl is the tool you will use in nearly every chapter to send one HTTP request and print the answer: a browser with no window.

What you should see: a first line beginning curl and a version number, then one or two lines listing protocols and features. Any recent version is fine.

Step 4 — Write down what you think you are building

Before the vocabulary arrives and rearranges your mental model, record the version you have now.

mkdir -p learnings

Create learnings/ch01.md and write one paragraph, in your own words, using no jargon from this chapter, answering: what is taskd, and who would pay for it? Five or six sentences.

This is a step and not a nicety because at Chapter 27 you will read it again. The distance between that paragraph and what you can write then is the only honest measure of what this book taught you.

7. Checkpoint: prove it works

One command chaining all four checks. && means “continue only if the previous command succeeded”, so the last word appears only if everything passed.

go version && docker compose version && curl --version | head -1 && \
  docker run --rm hello-world | grep -q "working correctly" && echo PREFLIGHT-OK

If you got something else:

8. Common mistakes (and the quick fix)

Almost nothing here is code, so most of this chapter’s mistakes are misunderstandings that surface much later.

9. Pitfalls

The original chapter has no pitfalls section, because it ships no code. These are the traps in the decisions — the ones that present a bill much later.

• Choosing by benchmark. Framework comparisons are won on requests per second, measured on an endpoint that does nothing. Every endpoint here waits on Postgres or Stripe, and that wait dwarfs the routing. Routing speed is not the tiebreaker at your scale; lock-in is.

• “We’ll split into microservices later” as a plan rather than a trigger. A plan with no condition never fires, or fires at the worst moment. Write the trigger instead: when one part needs different hardware, or a second team owns it, we split that part.

• Counting dependencies instead of measuring them. “Only four dependencies” is a number, not a property. One dependency whose types are in every signature costs more than eight that each live in one file. Apply the Nadh test per dependency, never to the total.

• Adopting the shape without the reasons. Copy this layout into your next project without being able to say why the driver choice is the cheap one, and you have adopted a cargo cult: the visible form of something that worked, minus the part that made it work.

10. Check yourself — quiz

1. Name the four decisions this chapter makes, and one reason for each answer.
2. chi is called “still net/http”. What specific, checkable fact does that claim rest on?
3. An ORM and a hand-written rows.Scan both go wrong. Describe each failure mode, and say which one a tool could catch before the program ran.
4. Why was lib/pq rejected, and why is that the cheapest of the four decisions to reverse?
5. What does “modular monolith” mean, and what condition would make you split it?
6. What does /v1 buy you, given that there is no /v2 and may never be one?
7. In the system diagram, which box calls Stripe, which direction does Prometheus’s arrow point, and which two boxes does this book not write?
8. You are offered a library that saves a day of work, but its own Session type would appear in the signature of all forty of your handlers. Apply this chapter’s test out loud.