Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

docs(sql-editor): record the TiDB version that prints tidb_json (#21676)

Danny Xu7b5fa47245db
diff --git a/backend/plugin/parser/tidb/explain.go b/backend/plugin/parser/tidb/explain.go
index 2575c32548..6b815cee46 100644
--- a/backend/plugin/parser/tidb/explain.go
+++ b/backend/plugin/parser/tidb/explain.go
@@ -16,6 +16,10 @@ func init() {
// tidbJSONFormat is TiDB's name for the plan as a tree of JSON objects. Its
// other JSON-ish format, plain `json`, TiDB rejects outright.
+//
+// TiDB added tidb_json in v6.5.0 (December 2022) and does not know the name
+// before it. Nothing here reads the server's version, so a server older than
+// that answers an explain request with its own error rather than a plan.
const tidbJSONFormat = "tidb_json"
// explainStatement implements base.ExplainStatement. TiDB spells its structured
diff --git a/docs/design/query-plan-visualizer.md b/docs/design/query-plan-visualizer.md
index ea1361a4e9..1a7f1b606d 100644
--- a/docs/design/query-plan-visualizer.md
+++ b/docs/design/query-plan-visualizer.md
@@ -563,6 +563,14 @@ to Text rather than erroring; engines change their output between versions, and
PostgreSQL 18 already reformatted part of it. An explain that the engine itself
rejects shows that error in the tab, like any failed query.
+The format a parser reads can also be newer than the server. TiDB prints
+`FORMAT=tidb_json` from v6.5.0 (December 2022) and does not know the name
+before it, so every TiDB that cannot answer predates that release; the editor
+asks for the format regardless rather than carry a version gate, and such a
+server shows that error where it used to show a text plan. The floors of the
+other structured formats are unmeasured; `json = 1, indexes = 1` makes
+ClickHouse the one worth measuring next.
+
---
## 4. Alternatives
diff --git a/frontend/src/apps/explain-visualizer/test-data/README.md b/frontend/src/apps/explain-visualizer/test-data/README.md
index 0d35869cc2..4785b2b669 100644
--- a/frontend/src/apps/explain-visualizer/test-data/README.md
+++ b/frontend/src/apps/explain-visualizer/test-data/README.md
@@ -190,7 +190,8 @@ To add one, the same client as above against a Doris frontend.
`EXPLAIN FORMAT=tidb_json` output from TiDB 8.5 against the same schema. TiDB
reports no cost in this format or any other the editor can ask for, so these
-plans carry rows alone.
+plans carry rows alone. It has printed these same keys since it added the
+format in v6.5.0, so one capture stands for every release that answers at all.
| File | Shape it covers |
| --- | --- |