Configuration

TiDB has three layers of configuration: command-line flags, the TOML config file, and SQL-level system variables. Most operational changes are made through system variables (changeable at runtime); the config file holds settings that need to be known at process start.

Command-line flags

Defined in cmd/tidb-server/main.go (the nm* constants near the top of the file enumerate them). Common flags:

| Flag | Purpose | | ------------------------------------------- | -------------------------------------------------------------- | --------- | --------------- | | -V | Print version and exit. | | --config <path> | Path to the TOML config file. | | --config-check, --config-strict | Validate the config and exit. | | --store=tikv | unistore | mocktikv | Storage driver. | | --path | PD endpoints (for tikv) or local data path (for unistore). | | --host, --P, --socket | Listening address for the SQL server. | | --advertise-address | Address advertised to other instances and PD. | | --status, --status-host | HTTP status server. | | --metrics-addr, --metrics-interval | Prometheus push gateway (optional). | | --lease | DDL lease duration (e.g., 45s). | | --tmp-storage-path, --tmp-storage-quota | Temporary spill directory for sort/agg. | | --token-limit | Concurrency token limit for new statements. | | --keyspace-name | Multi-tenant keyspace selection. | | --standby-cli | Run as standby (see pkg/standby/). | | --cors, --require-secure-transport | TLS / CORS toggles. |

Run bin/tidb-server -h for the full list against your build.

TOML config file

• Schema and defaults: pkg/config/config.go.
• An annotated example: pkg/config/config.toml.example.
• Reload semantics: most fields require restart; some are reload-on-SIGHUP via pkg/util/sysvar/.

Notable sections:

Section	Notes
[security]	TLS for SQL/status, cluster TLS, SSL-mode policies.
[performance]	Stats lease, max-procs, GC ratio, OOM action.
[opentracing]	Jaeger sampler config.
[tikv-client]	Region cache TTL, gRPC keepalive, async commit and 1PC toggles.
[isolation-read]	Engine selection (tikv, tiflash, tidb).
[log]	Log file path, level, slow-log threshold, redaction.
[experimental]	Feature flags for incubating features.
[instance]	Instance-only fields (no global default), e.g., tidb_server_memory_limit.
[status]	HTTP status port, record-db-qps.

System variables

Defined in pkg/sessionctx/variable/sysvar.go (over 240 KB and ~1,800 entries — TiDB owns one of the larger MySQL-flavour sysvar surfaces). Each variable declares scope (SESSION / GLOBAL / INSTANCE), default, validation, and an optional setter callback.

Categories worth knowing:

• tidb_* — TiDB-specific knobs.
• tidb_opt_* — optimizer factors and feature toggles. Examples: tidb_opt_cost_model_version, tidb_opt_join_reorder_threshold, tidb_opt_cpu_factor_v2.
• tidb_enable_* — feature flags. Examples: tidb_enable_clustered_index, tidb_enable_global_index, tidb_enable_strict_not_null_check (added very recently in commit 9d1ac814ec).
• tidb_resource_* — resource control.
• tidb_runaway_* — runaway query rules.
• MySQL-compatible — autocommit, time_zone, sql_mode, wait_timeout, etc.

Defaults are listed in pkg/sessionctx/variable/vardef/. The end-user reference is at https://docs.pingcap.com/tidb/stable/system-variables; the in-repo source is authoritative.

Cluster-wide vs instance settings

• Variables with Instance: true apply only to the instance that ran SET GLOBAL … and don't propagate.
• True global variables are stored in the mysql.global_variables system table and propagated through etcd; pkg/domain/sysvar_cache.go watches the etcd path and triggers a SysVarCache.Reload.

Errors

Every numbered error returned by TiDB is registered in errors.toml at the repo root. The file is generated by make errdoc from terror.NewError calls scattered across the codebase. Don't edit errors.toml by hand; modify the call site and re-run the script.

Logging

• Configuration: [log] in the TOML file.
• Levels: debug, info, warn, error, fatal.
• Output paths: main log, slow log, general log (off by default), audit log (via extension).
• Runtime change: POST /log/level on the status server, or SET tidb_log_level = 'debug'.