Glossary

A two-part lookup. First the Go-language terms — each links to the language chapter that teaches it. Then the domain terms from the example system, the distributed SQL proxy this guide reads as its running example. Entries are definitions only; follow the link for depth.

Go terms

goroutine : Lightweight thread scheduled by the Go runtime, not the OS. Started with go f(). Cheap to create (thousands+); leaks if it blocks forever on a channel with no sender/receiver. → Concurrency

channel : Typed conduit for passing values between goroutines. Unbuffered = synchronous handoff; buffered = queue of fixed capacity. Closing signals “no more values”; receiving from a closed channel yields the zero value. → Concurrency

select : Multiplexes over multiple channel operations; blocks until one is ready (or runs default if present). The idiom for combining a work channel with <-ctx.Done(). → Concurrency

context (Context) : Carries cancellation, deadlines, and request-scoped values across API/goroutine boundaries. Passed as the first arg, named ctx. Cancellation propagates down a derived-context tree. → Context

cancellation / deadline / timeout : A context.Context is cancelled explicitly (cancel()), at a fixed Deadline, or after a Timeout. Downstream code observes it via <-ctx.Done() and ctx.Err(). Always call the returned cancel (often defer cancel()). → Context

interface satisfaction (implicit) : A type satisfies an interface simply by having the required method set — no implements keyword, no declaration of intent. Satisfaction is checked structurally at compile time. → Interfaces & Composition

interface embedding : An interface listing another interface as a member, unioning their method sets (e.g. io.ReadCloser embeds Reader + Closer). → Interfaces & Composition

struct embedding / promotion : A struct field declared with no name; the embedded type’s fields and methods are promoted to the outer type. Composition, not inheritance — no dynamic dispatch from outer to embedded. → Interfaces & Composition

typed nil : A non-nil interface value whose dynamic value is a nil pointer. var p *T = nil; var i I = p makes i != nil even though the pointer is nil — a classic gotcha when returning concrete error types. → Interfaces & Composition

zero value : The value a variable holds before explicit initialization: 0, "", false, nil for pointers/slices/maps/channels/interfaces, and recursively-zeroed structs. Useful zero values (e.g. sync.Mutex, bytes.Buffer) are a deliberate API design goal. → Pointers, Values & Memory

value vs pointer semantics : Assignment and argument passing copy the value. Pointers (*T) share the underlying data; the choice affects mutation visibility, copy cost, and method-set rules. → Pointers, Values & Memory

escape analysis : Compile-time determination of whether a value can live on the stack or must “escape” to the heap (e.g. because a pointer to it outlives the function). Inspect with go build -gcflags=-m. → Pointers, Values & Memory

slice / map / string header : Slices and strings are small structs (pointer + len, slices add cap) over backing arrays; maps are pointers to a runtime hash table. Copying a slice copies the header, not the backing array — so two slices can alias the same memory. → Pointers, Values & Memory

append growth : append may reallocate the backing array when capacity is exceeded, returning a new slice header; this is why s = append(s, x) reassigns. Aliasing slices can silently diverge after a grow. → Pointers, Values & Memory

receiver : The value/pointer a method is defined on: func (r T) M() (value receiver) or func (r *T) M() (pointer receiver). Pointer receivers can mutate and avoid copies. → Types, Structs & Methods

method set : The set of methods callable on a type. *T’s method set includes both value- and pointer-receiver methods; T’s includes only value-receiver methods — which governs what interfaces T vs *T satisfy. → Types, Structs & Methods

error (interface) : The single-method interface `interface { Error() string }`. Errors are ordinary values, returned (usually last) and checked explicitly — not thrown. → Errors

error wrapping / chains : fmt.Errorf("...: %w", err) wraps an error, preserving the original for errors.Is / errors.As to unwrap. In this codebase, wrap with errx.Wrapf (see below) to keep stacktraces and canonical codes. → Errors

panic / recover : panic unwinds the stack running deferred funcs; recover (only meaningful inside a defer) stops the unwind. Reserved for truly unexpected / programmer-error situations, not ordinary control flow. → Sync & Memory Model

sync primitives : sync.Mutex/RWMutex, sync.WaitGroup, sync.Once, sync/atomic. Used when sharing memory rather than communicating over channels. → Sync & Memory Model

memory model / happens-before : The rules defining when one goroutine’s writes are guaranteed visible to another. Without synchronization (channel, mutex, atomic), concurrent access is a data race with undefined behavior; catch it with -race. → Sync & Memory Model

generics / type parameters : Functions and types parameterized by type, e.g. func Map[T, U any](...), constrained by interfaces (comparable, any, custom constraint sets). → Generics

package / module / visibility : A package is a directory of compiled-together .go files; a module (go.mod) is a versioned collection of packages. Identifiers starting with an uppercase letter are exported; lowercase are package-private. The example codebase is one module, github.com/example/platform. → Packages, Modules & Imports

init() : Per-file function(s) run automatically at package load, after variable initialization, before main. Used for registration side effects. → Packages, Modules & Imports

blank import : import _ "pkg" imports a package only for its init() side effects (e.g. registering a driver/backend). → Packages, Modules & Imports

internal/ : A directory named internal whose packages are importable only by code rooted at its parent — compiler-enforced encapsulation. → Packages, Modules & Imports

build tags / build constraints : //go:build lines that include or exclude a file per OS, arch, or custom tag — how platform-specific or test-only code is selected. → Packages, Modules & Imports

Domain terms

These come from the example system — a distributed SQL proxy, a set of small Go services in front of real PostgreSQL servers. They’re standard distributed-systems vocabulary, grounded in one real architecture.

Services and binaries

gateway : PostgreSQL proxy that accepts client connections and routes queries; the first hop in client → gateway → pooler → postgres. Lives at internal/gateway. → Architecture & Request Flow

pooler : Connection-pooling service that talks to PostgreSQL on behalf of the gateway. Each pooler has a topology record (Pooler) carrying its role, serving status, lifecycle, and shard membership. internal/pooler. → Service Anatomy, Architecture & Request Flow

dbctld : PostgreSQL Control Service — manages (starts, restarts, stops) PostgreSQL instances. It is the control daemon, not the database itself. internal/dbctld. → Architecture & Request Flow

orchestrator (orch) : Cluster orchestration service handling consensus and failover across cells — detects a dead leader and elects a new one. internal/orch. → Consensus, Orchestration & Failover

admin : Administrative service for cluster management. cmd/admin. → Architecture & Request Flow

platformctl (CLI) : Command-line tool for cluster management. cmd/platformctl. → Architecture & Request Flow

portpoolserver : Standalone binary providing port-pool allocation. cmd/portpoolserver (package main). → Architecture & Request Flow

Topology and sharding

cell : A zone / availability-zone grouping. The cluster topology is organized by cells, each with its own set of services. The Cell record (`name`, `server_addresses`, `root`) is stored in the global topology server and describes how to reach that cell’s topology service. Not the same as a shard. → Architecture & Request Flow

topology / topo : etcd-backed service-discovery and metadata store. The global topology stores Cell records; each cell’s topology stores per-cell metadata. Client and backends live in internal/topo (e.g. etcdtopo, memorytopo). → Architecture & Request Flow

shard / ShardKey / KeyRange : The sharding unit. A Pooler belongs to a shard via its shard_key; range-based sharding uses a key_range. Distinct from a cell (a zone). → Architecture & Request Flow

PoolerType : A pooler’s role / topology routing label: UNKNOWN=0, PRIMARY=1 (only PRIMARY allows DMLs), REPLICA=2 (read-only), DRAINED=3 (temporarily removed from serving). Orthogonal to serving status and lifecycle. → Architecture & Request Flow

PoolerServingStatus : Whether a pooler can serve queries right now: SERVING=0, NOT_SERVING=1, BACKUP=2, RESTORE=3. An axis independent of role and lifecycle. → Architecture & Request Flow

PoolerLifecycleStatus : Where a pooler is in its process lifecycle: LIFECYCLE_UNKNOWN=0, STARTING=1, ACTIVE=2, STOPPING=3, SHUTDOWN=4. The third orthogonal axis (vs. role and serving status). → Service Anatomy

Consensus and failover

leader / follower : The consensus-elected coordinator and the nodes that follow it. The correct vocabulary for orchestration / HA code. Distinct from postgres primary/standby/replica and from PoolerType PRIMARY/REPLICA — “primary” is overloaded, so the terms are kept separate on purpose. → Consensus, Orchestration & Failover

primary / standby / replica : PostgreSQL recovery-mode state (pg_is_in_recovery()). Used only when directly observing or configuring postgres replication — not a synonym for leader/follower. → Consensus, Orchestration & Failover

cohort : The set of poolers a coordinator uses for initial leader appointment and quorum. Persisted (cohort_members on ShardInitClaim) so a crash-retry reuses the same cohort for idempotency. → Consensus, Orchestration & Failover

DurabilityPolicy / quorum : Per-shard consensus quorum rules (`policy_name`, `policy_version`, `quorum_type`, `required_count`). Stored in each shard’s postgres and replicated via streaming replication. → Consensus, Orchestration & Failover

QuorumType : The quorum algorithm: QUORUM_TYPE_UNKNOWN=0, QUORUM_TYPE_AT_LEAST_N=3 (≥ N nodes from the discovered cohort), QUORUM_TYPE_MULTI_CELL_AT_LEAST_N=4 (≥ one node from each of the required cells). Note the non-contiguous enum numbers. → Consensus, Orchestration & Failover

consensus package : internal/consensus — the DurabilityPolicy interface (CheckAchievable pre-flight feasibility gate, CheckSufficientRecruitment candidacy/revocation, BuildSyncReplicationConfig), plus the concrete AtLeastNPolicy / MultiCellPolicy policies. → Consensus, Orchestration & Failover

Process and runtime

servenv : The shared service environment — process bootstrap covering the config registry, gRPC/HTTP servers, logging, and lifecycle hooks (OnInit, OnTerm, OnTermSync). internal/servenv (ServEnv struct). → Service Anatomy

lameduck : A grace period after SIGTERM during which the process keeps running before stopping. Controlled by --lameduck-period. On shutdown the service enters lameduck mode, fires OnTerm hooks, then OnTermSync, then sleeps the remainder. → Service Anatomy

config (Viper-based config helper) : A typed, layered, live-reloadable config wrapper over spf13/viper: config.Value[T], Configure, a Registry, and BindFlags. internal/config. → Configuration: a Viper-based config helper

Errors and observability

errx (the structured-error package) : The project’s structured-error package. Defines canonical gRPC-style error codes that propagate across RPCs, plus PostgreSQL SQLSTATE / PgDiagnostic builders. Idiom: wrap with errx.Wrapf (not fmt.Errorf) to preserve stacktraces and codes; handle errors by code, never by string-matching the message. internal/errx. → Errors Across Boundaries & Observability

canonical error code : One of a small fixed set of codes (matching gRPC’s names and numbers) attached to every error and propagated through RPC boundaries. Handle by code, not message text. → Errors Across Boundaries & Observability

PgDiagnostic / SQLSTATE : PostgreSQL-error representation (*PgDiagnostic) that implements error directly, preserving the full set of PG diagnostic fields — Severity, Code (the five-char SQLSTATE, also via .SQLSTATE()), Message, Detail, Hint, Position, and more — plus the MessageType byte ('E' error vs 'N' notice). → Errors Across Boundaries & Observability

Wire protocol

pgwire / pgprotocol : The PostgreSQL wire-protocol implementation the gateway speaks to clients (and toward postgres): internal/pgprotocol, with subpackages server/, client/, scram/ (SASL auth), protocol/ (message-type codes), pid/, bufpool/. → PG Wire & sqltypes

sqltypes : The value/type plumbing for query parameters and results, including wire-format bind-param packing (ParamsToProto / ParamsFromProto). → PG Wire & sqltypes