Server

pkg/server/ orchestrates a single CockroachDB node. It opens stores, starts the SQL/HTTP/gRPC/DRPC listeners, registers status and admin APIs, runs the multi-tenant server controller, and drains cleanly on shutdown. server.go is the entry point and is over 100 KB on its own.

Purpose

Wire every subsystem together for a running process and expose admin/status APIs. A *Server (host process) owns the *kvserver.Stores, the SQL stack, the gRPC servers, and the HTTP server. A *serverController (server_controller*.go) can host many *SQLServer instances inside the same process for multi-tenant deployments.

Directory layout

pkg/server/
├── server.go                     // ~100 KB: top-level Server type and lifecycle
├── server_sql.go                 // ~85 KB: SQL-only server (used for tenants)
├── server_controller*.go         // multi-tenant orchestration
├── server_http.go                // HTTP listener and middleware
├── grpc_server.go                // gRPC + DRPC plumbing
├── drpc_server.go                // DRPC adapter
├── admin.go                      // /admin/v1/ HTTP API (~125 KB)
├── status.go                     // /status/ + /_status/ HTTP API (~155 KB)
├── api_v2*.go                    // /api/v2/ HTTP API (databases, ranges, sql, …)
├── tenant.go                     // SQL-only tenant server (~58 KB)
├── tenant_*.go                   // tenant orchestration
├── node.go                       // ~110 KB: KV node abstraction
├── init.go                       // bootstrapping a brand-new cluster
├── drain.go                      // graceful shutdown
├── decommission.go               // decommission flows
├── auth.go (in authserver/)      // session cookie auth
├── settings_cache*.go            // settings persistence on the local store
├── settingswatcher/              // watch system.settings via rangefeed
├── tenantsettingswatcher/        // watch tenant settings overrides
├── systemconfigwatcher/          // legacy zone-config watcher
├── pgurl/                        // postgres URL helpers
├── application_api/              // application API helpers
├── debug/                        // /debug/ handlers
├── diagnostics/                  // diagnostics reporting
├── status/                       // status helpers (cgo, runtime, …)
├── srverrors/                    // server-side error helpers
├── serverpb/                     // proto APIs
├── serverctl/                    // server lifecycle control
├── telemetry/                    // telemetry reporting
└── testserver*.go                // *TestServer for integration tests (~96 KB)

Key types

Type	File	Description
Server	pkg/server/server.go	The full host process: KV stores, SQL, HTTP, RPC.
SQLServer	pkg/server/server_sql.go	A SQL-only server (used by tenants).
serverController	pkg/server/server_controller.go	Hosts many SQLServers in one process.
Node	pkg/server/node.go	The KV-side façade — registers stores, gossips, owns liveness.
TestServer	pkg/server/testserver.go	The same Server with test helpers.

Boot sequence

graph TD
  Start["server.NewServer"] --> Cfg["resolve config (storage, certs, addrs, settings)"]
  Cfg --> RPC["start gRPC + DRPC listeners"]
  RPC --> Stores["open stores (Pebble engines)"]
  Stores --> Bootstrap["init.go: bootstrap or join"]
  Bootstrap --> Liveness["start liveness, gossip, raft transports"]
  Liveness --> Replicas["replay raft logs, start replicas"]
  Replicas --> SQL["start SQLServer"]
  SQL --> HTTP["start HTTP listener (admin, status, /api/v2)"]
  HTTP --> Ready["ready: accept SQL connections"]

pkg/server/init.go distinguishes two paths:

• Bootstrap — first node ever; writes initial range descriptors, system schema, and cluster ID.
• Join — connect to existing nodes via gossip address(es); the cluster ID is fetched, and the node is added to liveness.

Admin / status / api/v2 APIs

CockroachDB exposes three HTTP API surfaces:

• /_status/ (status.go) — observability: nodes, ranges, hot ranges, sessions, traces, network maps. Source: pkg/server/status.go (~155 KB).
• /_admin/v1/ (admin.go) — administrative: cluster settings, jobs, locations, decommissioning. Source: pkg/server/admin.go (~125 KB).
• /api/v2/ (api_v2*.go) — newer REST surface with structured pagination and OpenAPI-style routes; covers databases, grants, ranges, SQL, schema introspection.

Authentication for these endpoints is handled by pkg/server/authserver/. The DB Console (pkg/ui/) consumes /api/v2/.

See api/index for endpoint groupings.

Multi-tenant orchestration

A multi-tenant deployment runs the host KV layer (single tenant ID 1) plus N SQL-only tenants. pkg/server/server_controller*.go provides:

• serverController — manages the per-tenant SQLServer lifecycles within one process.
• server_controller_http.go — routes HTTP traffic to the right tenant by inspecting the cluster cookie or HTTP header.
• server_controller_sql.go — routes pgwire connections to the right tenant.
• server_controller_channel_orchestrator.go — start/stop tenants on demand.

pkg/server/tenant.go (~58 KB) is the long-lived per-tenant SQL server. pkg/server/tenant_settings.go and pkg/server/tenantsettingswatcher/ propagate tenant cluster settings overrides.

Drain and decommission

• Drain (drain.go, drain_test.go) — a multi-phase shutdown: stop accepting new SQL connections, transfer leases away, finish in-flight Raft proposals, then exit.
• Decommission (decommission.go, decommissioning/) — mark a node as DECOMMISSIONING in liveness, move replicas off, then DECOMMISSIONED.

Embedded helpers

• testserver.go — used by every integration test in the repo via serverutils. Exposes the same Server plus knobs to inject testing behavior.
• profiler/ — periodic CPU/heap profiles dumped under the data directory.
• tracedumper/ — periodic Jaeger trace dumps.
• goroutinedumper/ — automatic goroutine dumps when memory is tight.

Cluster init

The cockroach init CLI subcommand drives server.bootstrapCluster. It creates the system schema, writes the cluster ID, initializes liveness, and gossips. This logic lives in pkg/server/init.go and pkg/server/initial_sql.go (which seeds initial users and roles).

Settings cache

pkg/server/settings_cache.go and pkg/server/settingswatcher/ keep the per-node view of system.settings up to date by subscribing to a rangefeed. New settings overrides apply within seconds without restart.

Entry points for modification

• A new HTTP API: extend api_v2*.go and add a route. Use srvtestutils for tests.
• A new admin RPC: extend pkg/server/serverpb/admin.proto, implement on *adminServer, run ./dev gen protobuf.
• A new lifecycle hook: register with *Server in server.go::Start or serverController.
• A new shutdown step: add to drain.go::doDrain. Order matters — read the existing comments.
• A new tenant capability: add to pkg/multitenant/tenantcapabilities/, gate the relevant API.

Related pages

• SQL — what SQLServer actually runs.
• KV server — what Node wraps.
• RPC — the connection management used by every API.
• Security — TLS and auth wired in here.
• features/multi-tenant — the bigger picture for serverController.
• API — the HTTP API surfaces this package implements.