Patterns and conventions

The repository's contribution rules are defined formally in AGENTS.md (root) and CLAUDE.md (which inherits from AGENTS.md). This page summarises the patterns that show up most often in the codebase. For policy-level "MUST/SHOULD" rules, the source of truth remains AGENTS.md.

Non-negotiables (from AGENTS.md)

1. Correctness first. TiDB is a distributed SQL database; small changes can alter SQL semantics, consistency, or cluster behaviour.
2. No speculative behaviour. Do not invent APIs, defaults, protocol behaviour, or test workflows.
3. Keep diffs minimal. Avoid unrelated refactors, broad renames, or formatting-only churn.
4. Leave verifiable evidence — exact commands and their output.
5. Respect generated code. Do not hand-edit parser.go, the pkg/util/collate/ucadata/*_generated.go files, or anything regenerated by go generate.

Code style

• Go and gofmt: make fmt runs gofmt -s plus a interface{} -> any rewrite (Makefile's fmt target). The repo is fully on Go 1.25 features and uses any everywhere.
• Linters: make lint runs revive (tools/check/revive.toml) and a Grafana dashboard linter. make check-static runs golangci-lint against .golangci.yml.
• License header: every new *.go file must start with the standard Copyright … PingCAP, Inc. Apache 2.0 header. Copy from a neighbouring file and update the year if needed.
• Naming: code should be self-documenting. When implementing a known algorithm, name things so the approach is recognisable; add a short comment when intent isn't obvious.

Error handling

• Errors flow through github.com/pingcap/errors and are documented in errors.toml at the repo root. The make errdoc target regenerates the file via tools/check/check-errdoc.sh. Do not edit errors.toml by hand — register errors via terror.NewError(...).
• Components return their domain-specific error categories (for example pkg/parser/terror/, pkg/kv/error.go, pkg/store/driver/error/). New errors should be defined alongside the package that owns them and surfaced via terror.ErrCode.
• Never silently swallow errors. The lint config flags this. When wrapping, attach actionable context.

Tests and testdata

The test policy lives in AGENTS.md -> Quick Decision Matrix and docs/agents/testing-flow.md. Highlights:

• Prefer extending existing test suites and fixtures over creating new scaffolding.
• Failpoint-using tests run via ./tools/check/failpoint-go-test.sh <pkg> -run TestX. The script enables and disables failpoints around the run.
• Integration tests under tests/integrationtest/t/ and expected outputs under tests/integrationtest/r/ are recorded with tests/integrationtest/run-tests.sh -r <name>.
• RealTiKV tests under tests/realtikvtest/ require a tiup playground --mode tikv-slim --tag realtikvtest running in the background; cleanup is mandatory after the run.
• Bug fixes must include a regression test that fails before the fix and passes after.

Cross-package conventions

• Context first. Every function that performs IO or runs SQL takes a context.Context as its first parameter. Cancellation is honoured for queries, DDL jobs, and KV requests.
• Session context. Most planner/executor functions take a sessionctx.Context (pkg/sessionctx/) which carries the live transaction, infoschema, statistics, system variables, and statement context (StmtCtx). Functions that need a context-free interface usually accept a smaller expression.EvalContext or planctx.PlanContext.
• StmtCtx. pkg/sessionctx/stmtctx/ holds per-statement state — runtime stats, warnings, in-handle truncation flags, time zone, character set. Many code paths depend on it; always thread it through.
• Chunk. The vectorized execution model uses pkg/util/chunk/Chunk everywhere — operators take a chunk, append rows column-by-column, and pass it on. Don't re-allocate chunks per call; reuse the buffer the caller provided.
• Failpoints. Heavy use of github.com/pingcap/failpoint. Production builds compile failpoints out by default; tests enable them via the helper script. Never leave a failpoint set across tests.
• Generated code. pkg/parser/parser.go, pkg/parser/hintparser.go, the UCA collation tables, and the vectorized expression *_vec_generated.go files are all generated. Edit the source (.y files, pkg/expression/generator/, etc.) and regenerate via make parser or go generate ./....

Concurrency

• TiDB makes heavy use of goroutines for IO and background work. Long-running goroutines must respect context.Done() and use the pkg/util/wait and tidbutil.WithRecovery helpers (pkg/util/wait/, pkg/util/) so panics are logged with stack traces.
• Many subsystems own their own pool — pkg/resourcemanager/pool/spool and pkg/resourcemanager/pool/workerpool for general workers, pkg/util/gpool/ for goroutine reuse — rather than spawning ad-hoc goroutines.
• When holding a kv.Transaction across goroutines, the caller is responsible for serialising access. The pkg/sessiontxn/ package centralises transaction handoff.

DDL-specific rules

AGENTS.md calls out a separate DDL playbook:

• Before any DDL change, read docs/agents/ddl/README.md.
• DDL state machines must respect rollback semantics in pkg/ddl/rollingback.go and the cancel paths in pkg/ddl/cancel_test.go.
• Schema versioning lives in pkg/ddl/schema_version.go; a new DDL must bump or reuse version tracking correctly so other TiDB nodes converge.

Issue and PR conventions

• PR title format: pkg [, pkg2]: what is changed or *: what is changed.
• PR description must use .github/pull_request_template.md and include Issue Number: close #<id> (or ref #<id>).
• Keep HTML comment markers (Tests <!-- At least one of them must be included. -->) intact — CI tooling parses them.
• Don't git push --force without --force-with-lease, and avoid it on shared branches entirely.

Where to dig deeper

• Repo-wide conventions: AGENTS.md.
• Subsystem maps: docs/agents/architecture-index.md.
• Skills the repo expects agents to use: .agents/skills/ (operational playbooks for failpoints, integration test recording, real-TiKV runs, and verification profile selection).