Further Reading

Unlike the rest of the reference track, this page is mostly external links — the docs, blog posts, and specs worth reading alongside each module. They’re grouped to match the guide’s tracks, so you can jump from a lesson straight to its primary sources.

A few ground rules for trusting these:

• Prefer the canonical docs (go.dev, protobuf.dev, grpc.io, postgresql.org) for anything spec-level. Blog posts are marked (blog) — great for intuition, not for resolving an argument.
• The Go spec, memory model, and generics are stable. Treat version-specific release notes as history, not as normative.

Note

The example codebase tracks a recent Go release (Go 1.25 at time of writing). Nothing here is pinned to a patch version — the language fundamentals these links cover don’t move between point releases.

Language track

The bedrock. Start with the spec and Effective Go; the rest are deep dives on one topic each.

Packages, modules, imports

The Go Programming Language SpecificationThe canonical language definition: packages, scope, declarations.

How to Write Go CodeModule layout, the go tool, and how package paths work.

Go Modules Referencego.mod semantics, minimal version selection, replace/exclude directives.

A Tour of GoThe fastest hands-on intro for an experienced programmer.

See Packages, Modules & Imports.

Types, structs, methods

Resource	Why it matters
Effective Go	Idiomatic struct/method design; the canonical style reference.
Go spec: Types	Method sets, named vs. composite types, embedding rules.

See Types, Structs & Methods.

Interfaces & composition

Resource	Why it matters
Effective Go: Interfaces	The “small interface” idiom.
Go Code Review Comments	Interface naming, “accept interfaces, return structs”, receiver types.
Go Proverbs	Rob Pike’s distilled wisdom — “the bigger the interface, the weaker the abstraction.”

See Interfaces & Composition.

Pointers, values, memory

Resource	Why it matters
Go Slices: usage and internals (blog)	The slice header (ptr/len/cap) — the mental model that prevents aliasing bugs.
Arrays, slices: the mechanics of append (blog)	Why append may or may not reallocate.
Effective Go: Pointers vs. Values	When a method needs a pointer receiver.

See Pointers, Values & Memory.

Errors

Resource	Why it matters
Error handling and Go (blog)	Errors as values; the original rationale.
Working with Errors in Go 1.13 (blog)	%w wrapping, errors.Is / errors.As.
errors package docs	Canonical API for Is / As / Join / Unwrap.

See Errors.

Generics

Resource	Why it matters
An Introduction to Generics (blog)	Type parameters and constraints.
When to Use Generics (blog)	The decision boundary — avoids over-abstraction.
Tutorial: Generics	A worked example, official.

See Generics.

Concurrency

Resource	Why it matters
Go Concurrency Patterns: Pipelines and cancellation (blog)	Fan-out/fan-in with clean shutdown — the request-path pattern.
Share Memory by Communicating (blog)	The channel-first design philosophy.
errgroup docs	Bounded concurrent work with first-error cancellation, as used in the codebase.

See Concurrency.

Context

Resource	Why it matters
Go Concurrency Patterns: Context (blog)	Cancellation/deadline propagation across API boundaries.
context package docs	Canonical WithCancel / WithTimeout / WithValue semantics.

See Context.

sync & the memory model

Resource	Why it matters
The Go Memory Model	Canonical happens-before rules — the basis for all correct synchronization.
sync package docs	Mutex, RWMutex, Once, WaitGroup.
sync/atomic docs	Typed atomics (atomic.Int64, atomic.Pointer).

See sync & the Memory Model.

Stdlib & idioms

Resource	Why it matters
Effective Go	The idiom baseline.
Go Code Review Comments	Per-construct style conventions reviewers expect.
slices / maps / cmp	Generic stdlib helpers (Go 1.21+).

See Stdlib & Idioms.

Testing

Resource	Why it matters
testing package docs	T, B, subtests, t.Helper, t.Cleanup.
Using Subtests and Sub-benchmarks (blog)	Table-driven structure with t.Run.
goleak docs	Goroutine-leak detection, wired into the codebase’s test utilities.

See Testing.

Project track

These cover the real systems behind the running example — the proxy/pooler architecture, the RPC stack, the SQL parser, the wire protocol, and consensus. The asides flag where the codebase reuses an idea rather than the linked implementation.

Architecture & request flow

Resource	Why it matters
Vitess docs	A mature distributed SQL proxy for MySQL — shared conceptual lineage with the example system.
What Is Vitess	The proxy/pooler/orchestrator split that the gateway/pooler/orchestrator services mirror.

Lineage, not implementation

The example system reimplements these ideas for Postgres. Don’t assume Vitess code or its VTGate/VTTablet APIs apply directly.

See Architecture & Request Flow and Service Anatomy.

cmd & Cobra

Resource	Why it matters
Cobra docs (repo)	The command-tree/flags/subcommands framework every binary uses.
pflag docs	The POSIX flag parsing underpinning Cobra.

See cmd & Cobra.

Config

Resource	Why it matters
Viper docs	Layered config (flags/env/file) that the config layer wraps.
fsnotify docs	Background for config live-reload (file watching).

See Config.

gRPC & Protobuf

Resource	Why it matters
Protocol Buffers docs	.proto syntax, types, and schema evolution.
Go Generated Code guide	What protoc-gen-go emits and how to use it.
gRPC-Go docs	Server/client stubs from protoc-gen-go-grpc.
grpc-gateway docs	REST/JSON transcoding via protoc-gen-grpc-gateway.

Note

All three plugins (protoc-gen-go, protoc-gen-go-grpc, protoc-gen-grpc-gateway) are driven from a single codegen target in the build.

See gRPC & Protobuf.

Parser, lexer, AST, codegen

Resource	Why it matters
PostgreSQL: The Parser Stage	The grammar model the SQL parser follows.
PostgreSQL gram.y source	The authoritative rule reference the in-repo grammar derives from.
golang.org/x/tools/cmd/goyacc	Go’s yacc port — lineage of the in-repo generator.

Note

The in-repo goyacc is a vendored variant (descended from Inferno’s iyacc and the Vitess goyacc, with local edits). Treat the linked Go/Vitess tools as lineage, not the exact tool the codebase runs.

See Parser, Lexer, AST & Codegen.

PG wire protocol & sqltypes

Resource	Why it matters
PostgreSQL Frontend/Backend Protocol	The wire protocol the pgprotocol package implements; a conformance suite runs against it.
Protocol Message Formats	Byte-level message layouts for encoding/decoding.
pgx/v5 docs	A reference Go PG implementation; used as a client in tests.

See PG Wire & sqltypes.

Consensus & failover

Resource	Why it matters
In Search of an Understandable Consensus Algorithm (Raft)	Background theory for leader election and log replication.
etcd docs	The etcd v3 client is used for topology and service discovery.

Background only

The consensus here is a custom coordinator doing leader election and appointment — not a turnkey Raft library. The Raft paper is for intuition.

See Consensus & Failover.

errors & observability

Resource	Why it matters
OpenTelemetry Go docs	The metrics/tracing stack (go.opentelemetry.io/otel).
log/slog docs	The structured logging used across services.
gRPC status codes	How RPC errors map to codes the error layer must translate.
Prometheus docs	Background for the metrics catalog and exposition.

See Errors & Observability.

Tooling track

The conventions and tools that the build, lint, and codegen workflows lean on.

Resource	Module
Conventional Commits	Build & Make — the commit/PR convention the project follows.
golangci-lint docs	Lint & Format
gofumpt · goimports	Lint & Format — formatters configured with a local import prefix.
Go Generated Code guide	Modules, Deps & Codegen

See also

GlossaryTerms used throughout the guide — cell, shard, pooler-type, leader/primary.

CheatsheetCommands and quick lookups for everyday work in the codebase.

Idioms & GotchasGo pitfalls and codebase-specific traps worth knowing.

OrientationThe map and the reading skills — start here if you haven't.