TiDB reads its configuration from a TOML file. By default,Documentation Index
Fetch the complete documentation index at: https://mintlify.com/pingcap/tidb/llms.txt
Use this file to discover all available pages before exploring further.
tidb-server looks for no config file and uses built-in defaults. Pass a config file explicitly with the --config flag:
Only a subset of options can be changed at runtime via the HTTP status API. Most options require a server restart to take effect.
Server
Top-level keys that control howtidb-server exposes itself to clients.
IP address the MySQL protocol listener binds to.
TCP port for MySQL client connections.
Unix domain socket path for local client connections. The
{Port} placeholder is replaced with the actual port value.IP address advertised to other TiDB components and clients. Useful when the host has multiple interfaces. Defaults to
host when empty.Maximum number of concurrent sessions. Requests beyond this limit are queued.
Storage
Storage backend. Accepted values:
| Value | Description |
|---|---|
tikv | Distributed storage via a running TiKV cluster (production) |
unistore | Built-in single-node store, no external dependencies (development) |
mocktikv | In-memory mock, for testing only |
Data directory used by the
unistore and mocktikv backends. When store = "tikv" this is the PD cluster address (e.g. "127.0.0.1:2379").Log
Configured under the[log] section.
Minimum log level. Accepted values (in increasing severity):
debug, info, warn, error, fatal.Log output format. Use
"json" for structured logging pipelines; "text" for human-readable output.File to write slow query records. Set to
"" to merge slow query logs into the main log.Log file rotation ([log.file])
Path to the log file. When empty, logs are written to stderr.
Maximum size of a single log file in megabytes (upper limit: 4096 MB). A new file is created when this size is reached.
Number of days to retain old log files.
0 disables time-based cleanup.Maximum number of rotated log files to keep.
0 disables count-based cleanup.Performance
Configured under the[performance] section.
Interval at which TiDB refreshes table statistics from storage. Shorter values produce fresher stats at the cost of more background I/O.
Maximum number of statements allowed inside a single transaction.
Number of OS threads (
GOMAXPROCS). 0 uses all available CPU cores.Security
Configured under the[security] section.
Path to the PEM file containing trusted CA certificates for MySQL client connections. TLS is disabled when this and the cert/key paths are all empty.
Path to the X.509 certificate in PEM format presented to MySQL clients.
Path to the private key in PEM format corresponding to
ssl-cert.Set
auto-tls = true under [security] to let TiDB generate a self-signed certificate automatically on first start. This is the recommended approach for development environments.Memory
Total memory limit for the
tidb-server process in bytes. 0 means unlimited — TiDB will use as much memory as the OS allows.Maximum disk space in bytes for temporary files spilled to disk when a query exceeds its memory limit.
-1 means TiDB does not check available capacity.Minimal configuration example
Dynamic configuration via HTTP API
You can view the current running configuration and update select settings at runtime via the HTTP status API (default port10080):
POST /settings (a separate endpoint):
Runtime changes made via
/settings are not persisted to disk. Update config.toml and restart tidb-server to make changes permanent. See the Administration API for the full list of settable parameters.