Skip to main content

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.

Use the tools below to diagnose issues in a running TiDB cluster. The HTTP Status API, slow query log, INFORMATION_SCHEMA tables, and the EXPLAIN statement are the primary diagnostic surfaces.

Identifying slow queries

TiDB writes slow queries (exceeding tidb_slow_log_threshold, default 300ms) to the slow query log and to INFORMATION_SCHEMA.SLOW_QUERY.View recent slow queries:
SELECT query, query_time, mem_max, plan
FROM INFORMATION_SCHEMA.SLOW_QUERY
ORDER BY query_time DESC
LIMIT 10;
Analyze a query with EXPLAIN:
EXPLAIN SELECT * FROM orders WHERE customer_id = 123;
Analyze a query with actual runtime statistics:
EXPLAIN ANALYZE SELECT * FROM orders WHERE customer_id = 123;
EXPLAIN ANALYZE executes the query and returns the actual rows, loops, and time spent at each operator. Look for operators with high actRows vs estRows discrepancy — this often indicates stale statistics.Update table statistics:
ANALYZE TABLE orders;
Check if an index is being used:Look for IndexScan or IndexLookUp in EXPLAIN output. A full TableScan on a large table is a common cause of slow queries.

Diagnosing high memory usage

TiDB enforces per-query and per-instance memory limits.Check the current memory quota per query:
SHOW CONFIG WHERE name = 'mem-quota-query';
Or in a session:
SELECT @@tidb_mem_quota_query;
Set a session-level limit:
SET SESSION tidb_mem_quota_query = 1073741824; -- 1 GiB
Check current memory usage of running queries:
SELECT id, user, db, command, time, state, info, mem
FROM INFORMATION_SCHEMA.PROCESSLIST
ORDER BY mem DESC
LIMIT 10;
Kill a query consuming excessive memory:
KILL TIDB <connection-id>;
If queries are consistently hitting the memory limit, consider adding indexes to reduce the data scanned, or increase mem-quota-query in tidb.toml.
Configure the server-level memory limit in tidb.toml:
[performance]
# Maximum memory available to TiDB in bytes. 0 means use total system memory.
server-memory-quota = 0

Diagnosing connection failures

TiDB accepts MySQL connections on port 4000 by default.Verify TiDB is listening:
curl http://127.0.0.1:10080/status
Test a direct connection:
mysql -h 127.0.0.1 -P 4000 -u root
Common causes and fixes:
SymptomLikely causeResolution
Connection refused on port 4000TiDB not running or firewallCheck process and firewall rules
Too many connections errormax-server-connections limit reachedIncrease limit or add TiDB nodes
TLS handshake failureCertificate mismatch or expired certCheck ssl-ca, ssl-cert, ssl-key in config
Authentication failureWrong credentials or host restrictionCheck mysql.user for allowed hosts
Check current connection count:
curl http://127.0.0.1:10080/status | python3 -m json.tool
Configure maximum connections in tidb.toml:
[server]
max-server-connections = 4096

Diagnosing DDL failures

TiDB DDL operations run asynchronously. If a DDL job fails, inspect the job history.Check DDL job history via HTTP API:
curl http://127.0.0.1:10080/ddl/history
Check DDL job status in SQL:
-- View running DDL jobs
ADMIN SHOW DDL JOBS;

-- View recently completed or failed DDL jobs
ADMIN SHOW DDL JOBS 20;
The STATE column shows done, running, cancelling, or rollback done. A job in rollback done state encountered an error; check the ERROR column for details.Cancel a running DDL job:
ADMIN CANCEL DDL JOBS <job-id>;
Common DDL failure causes:
  • Duplicate key violations when adding a unique index
  • Insufficient disk space on TiKV nodes
  • Schema version conflicts in a multi-TiDB-node setup (usually transient)

Diagnosing lock contention

TiDB uses optimistic and pessimistic transactions. Lock contention appears as slow transactions or Deadlock errors.View current lock waits:
SELECT * FROM INFORMATION_SCHEMA.DATA_LOCK_WAITS;
This shows which transactions are blocking others, including the blocking and waiting transaction IDs and the locked key.View deadlock history:
SELECT * FROM INFORMATION_SCHEMA.DEADLOCKS;
Check active transactions:
SELECT * FROM INFORMATION_SCHEMA.TIDB_TRX;
Mitigation strategies:
  • Use pessimistic transactions (BEGIN PESSIMISTIC) for workloads with high write contention
  • Keep transactions short; avoid holding locks across network round trips
  • Use SELECT ... FOR UPDATE only where necessary
  • Add indexes to reduce the number of rows scanned per transaction
-- Switch a session to pessimistic mode
SET SESSION tidb_txn_mode = 'pessimistic';

TiDB log locations and format

TiDB writes structured JSON logs by default. In a TiUP deployment, logs are in ~/.tiup/logs/.
# View logs for a named cluster
tiup cluster display <cluster-name>
# Then SSH to the node and check the log path shown in the output
Search for errors in the log:
grep '"level":"error"' /path/to/tidb.log | tail -50
Key log fields:
FieldMeaning
levelinfo, warn, error, fatal
msgHuman-readable message
errError string if applicable
querySQL statement (may be truncated)
connConnection ID, correlates with PROCESSLIST
Increase log verbosity temporarily:
SET GLOBAL tidb_log_level = 'debug';
-- Remember to restore after diagnosis:
SET GLOBAL tidb_log_level = 'info';

Useful INFORMATION_SCHEMA tables

TablePurpose
INFORMATION_SCHEMA.SLOW_QUERYSlow query log with execution plans
INFORMATION_SCHEMA.PROCESSLISTActive connections and running queries
INFORMATION_SCHEMA.TIDB_TRXActive transactions
INFORMATION_SCHEMA.DATA_LOCK_WAITSCurrent lock wait graph
INFORMATION_SCHEMA.DEADLOCKSRecent deadlock history
INFORMATION_SCHEMA.CLUSTER_INFOTopology and version of all cluster components
INFORMATION_SCHEMA.METRICS_TABLESPrometheus metrics queryable via SQL

HTTP API diagnostic endpoints

# Server status and connection count
curl http://127.0.0.1:10080/status

# DDL job history
curl http://127.0.0.1:10080/ddl/history

# All Prometheus metrics
curl http://127.0.0.1:10080/metrics

# Region metadata
curl http://127.0.0.1:10080/regions/meta

# Hot regions by table
curl http://127.0.0.1:10080/regions/hot

Build docs developers (and LLMs) love