Glossary

A two-part lookup. First the Go-language terms — each links to the language chapter that teaches it. Then the domain terms from multigres, the distributed-systems codebase 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 mterrors.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/multigres/multigres. → 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 multigres — Vitess for Postgres, a set of small Go services in front of real PostgreSQL servers. They’re standard distributed-systems vocabulary, grounded in one real system.

Services and binaries

multigateway : PostgreSQL proxy that accepts client connections and routes queries; the first hop in client → multigateway → multipooler → postgres. Lives at go/services/multigateway. → Architecture & Request Flow

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

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

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

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

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

portpoolserver : Standalone binary providing port-pool allocation. go/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 go/common/topoclient (e.g. etcdtopo, memorytopo). → Architecture & Request Flow

shard / ShardKey / KeyRange : The sharding unit. A MultiPooler 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 : go/common/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). go/common/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

viperutil : A typed, layered, live-reloadable config wrapper over spf13/viper: viperutil.Value[T], Configure, a Registry, and BindFlags. → Configuration: viper & viperutil

Errors and observability

mterrors : The codebase’s error package. Defines canonical gRPC-style error codes that propagate across RPCs, plus PostgreSQL SQLSTATE / PgDiagnostic builders. Idiom: wrap with mterrors.Wrapf (not fmt.Errorf) to preserve stacktraces and codes; handle errors by code, never by string-matching the message. go/common/mterrors. → 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): go/common/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