Skip to content

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

chore(tidb): trim verbose godoc in omni shim + bridge (BYT-9396) (#20479)

Vincent Huang72a33611f6f0
diff --git a/backend/plugin/advisor/tidb/utils.go b/backend/plugin/advisor/tidb/utils.go
index ab9585bb11..cd3ade5872 100644
--- a/backend/plugin/advisor/tidb/utils.go
+++ b/backend/plugin/advisor/tidb/utils.go
@@ -57,9 +57,9 @@ func (t tablePK) tableList() []string {
return tableList
}
-// getTiDBNodes extracts pingcap-AST nodes. Post-dml_dry_run migration (PR
-// #20467) its only consumer is advisor_builtin_prior_backup_check, which uses
-// pingcap AST for authoritative DDL detection on its dual-path (cumulative #30).
+// getTiDBNodes extracts pingcap-AST nodes. Its only consumer is
+// advisor_builtin_prior_backup_check, which uses pingcap AST for authoritative
+// DDL detection on its dual-path.
//
// On a PingCapASTProvider whose AsPingCapAST returns (nil, false) — i.e.
// the bridge tried and pingcap rejected the statement — the statement is
@@ -708,29 +708,16 @@ func omniNeedDefault(col *omniast.ColumnDef) bool {
// this cache.
const omniStmtsCacheKey = "tidb.omniStmts"
-// getTiDBOmniNodes returns omni-parsed statements for migrated advisors.
+// getTiDBOmniNodes returns omni-parsed statements for migrated advisors. The
+// dispatcher has already parsed and populated stmt.AST; this helper unwraps the
+// nodes and memoizes the result on checkCtx.Memo (one parse per review).
//
-// Post-flip (Phase 1.5 §1.5.N+1): the dispatcher in
-// backend/plugin/parser/tidb/dispatcher.go has already done the omni parse
-// and populated stmt.AST. This helper just unwraps OmniAST nodes and
-// preserves the cache contract.
-//
-// Three-arm type switch (per plan §1.5.0 invariant #8):
+// Type switch over stmt.AST:
// - *tidbparser.OmniAST: omni accepted — collect the node.
-// - *tidbparser.AST: dispatcher fell back to pingcap (omni rejected this
-// statement). Skip — migrated advisors emit no advice for omni-rejected
-// SQL. Soft-fail invariant preserved end-to-end (responsibility moved
-// from this helper to the dispatcher).
-// - default: unknown AST type. Warn (mandatory per invariant #8 — a
-// future engine introducing a third AST type for tidb shouldn't
+// - *tidbparser.AST: dispatcher fell back to pingcap (omni rejected the
+// statement). Skip — migrated advisors emit no advice for omni-rejected SQL.
+// - default: unknown AST type — warn (a future third tidb AST type shouldn't
// silently drop statements).
-//
-// Cache contract (single-parse-per-review): the result slice is memoized
-// on checkCtx.Memo so subsequent calls within the same review return the
-// identical slice without re-walking the type switch. The dispatcher's
-// parse already happened once at split time, so this cache amortizes only
-// the type-switch + slice construction now — but the contract (one
-// observable parse per review) is preserved.
func getTiDBOmniNodes(checkCtx advisor.Context) ([]OmniStmt, error) {
if cached, ok := checkCtx.Memo(omniStmtsCacheKey); ok {
if stmts, typeOK := cached.([]OmniStmt); typeOK {
@@ -755,10 +742,9 @@ func getTiDBOmniNodes(checkCtx advisor.Context) ([]OmniStmt, error) {
BaseLine: stmt.BaseLine(),
})
case *tidbparser.AST:
- // Dispatcher fell back to pingcap for this statement (omni
- // rejected). Migrated advisors skip it; un-migrated advisors
- // using getTiDBNodes still see the pingcap AST. Soft-fail
- // per invariant #2 preserved.
+ // Dispatcher fell back to pingcap (omni rejected this statement).
+ // Migrated advisors emit no advice for omni-rejected SQL, so skip;
+ // getTiDBNodes consumers still see the pingcap AST.
continue
default:
slog.Warn("unexpected stmt.AST type for tidb dispatcher",
diff --git a/backend/plugin/parser/tidb/omni.go b/backend/plugin/parser/tidb/omni.go
index f22d0c539e..596f5686b9 100644
--- a/backend/plugin/parser/tidb/omni.go
+++ b/backend/plugin/parser/tidb/omni.go
@@ -13,26 +13,10 @@ import (
// OmniAST wraps an omni/tidb AST node and implements the base.AST interface.
//
-// During the Phase 1.5 advisor migration, OmniAST also implements
-// PingCapASTProvider so that callers still using GetTiDBAST() (~50 of 51
-// un-migrated advisors at any given point in the migration) can fall back to
-// a native pingcap-parsed AST. After the dispatcher flip (§1.5.N+1) returns
-// *OmniAST from ParseStatements, those un-migrated advisors keep working
-// because GetTiDBAST routes through AsPingCapAST() automatically.
-//
-// The PingCapASTProvider bridge is retained after the dml_dry_run migration
-// (PR #20467): its sole remaining consumer is advisor_builtin_prior_backup_check,
-// which reads pingcap AST for authoritative DDL detection on its dual-path
-// (cumulative #30). Removal is gated on that consumer moving its DDL detection
-// off pingcap (deemed brittle, deferred) — NOT on any advisor migration. (This
-// is distinct from the dispatcher's Option B pingcap-fallback for omni-rejected
-// SQL, which persists until Option A retirement; see dispatcher.go + invariant
-// #8 in plans/2026-04-23-omni-tidb-completion-plan.md §1.5.0.)
-//
-// Mirrors backend/plugin/parser/mysql/omni.go's AsANTLRAST pattern:
-// - Lazy parse + cache via pingcapParsed flag (matches mysql's antlrParsed).
-// - Single bridge call per OmniAST instance regardless of how many advisors
-// consume it (50+ per review under flip-last + cache).
+// It also implements PingCapASTProvider: AsPingCapAST() lazily produces a
+// native pingcap-parsed AST for the one remaining consumer that needs it,
+// advisor_builtin_prior_backup_check, which uses pingcap AST for authoritative
+// DDL detection. The pingcap parse is cached per OmniAST instance.
type OmniAST struct {
// Node is the omni AST node (e.g. *ast.SelectStmt, *ast.CreateTableStmt).
Node ast.Node
@@ -41,10 +25,7 @@ type OmniAST struct {
// StartPosition is the 1-based position where this statement starts.
StartPosition *storepb.Position
- // pingcapAST is lazily populated when AsPingCapAST() is called for the
- // first time. Cached for the lifetime of this OmniAST instance.
- // Retained for the prior_backup_check dual-path (cumulative #30); see the
- // type doc above.
+ // pingcapAST is lazily populated and cached on the first AsPingCapAST() call.
pingcapAST *AST
// pingcapParsed tracks whether we've attempted the native parse, to
// distinguish "not yet parsed" from "parsed and got nil".
@@ -56,29 +37,16 @@ func (a *OmniAST) ASTStartPosition() *storepb.Position {
return a.StartPosition
}
-// AsPingCapAST implements PingCapASTProvider for backward compatibility with
-// un-migrated advisors during the Phase 1.5 migration window. Lazily parses
-// the SQL text with the native pingcap parser and caches the result.
+// AsPingCapAST lazily parses the statement text with the native pingcap parser,
+// caches the result, and returns it.
//
-// Implementation notes:
-// - Calls ParseTiDB strictly (no error-recovery mode). Unlike mysql's
-// parseSingleStatementLenient, pingcap has no equivalent error-recovery
-// mode — it either parses fully or errors. For the bridge case (omni
-// already validated the SQL syntax) strict parsing is correct.
-// - Sets OriginTextPosition + per-column lines (CREATE TABLE) via the
-// shared applyTiDBLineTracking helper, so post-flip un-migrated advisors
-// that read node.OriginTextPosition() see the same line numbers as the
-// pre-flip canonical path (ParseTiDBForSyntaxCheck).
+// - Uses strict parsing (no error recovery); for the bridge case the syntax
+// is already omni-validated.
+// - Applies applyTiDBLineTracking so node.OriginTextPosition() and CREATE
+// TABLE per-column lines match the canonical ParseTiDBForSyntaxCheck path.
//
-// Returns (nil, false) if the native parser fails to parse the text. In that
-// case un-migrated advisors get no AST for this statement and emit no advice
-// — symmetric with the omni-side soft-fail in
-// advisor/tidb/utils.go.getTiDBOmniNodes. This bridge protects review
-// continuity when omni successfully wraps a statement but pingcap
-// subsequently rejects it. The orthogonal failure mode — omni rejects at the
-// dispatcher level so no *OmniAST exists for the bridge to operate on — is
-// handled by the dispatcher-fallback contract (plan §1.5.0 invariant #8,
-// shipping with the dispatcher flip in §1.5.N+1).
+// Returns (nil, false) if pingcap fails to parse the text; the caller then sees
+// no AST for the statement and emits no advice.
func (a *OmniAST) AsPingCapAST() (*AST, bool) {
if a.pingcapParsed {
return a.pingcapAST, a.pingcapAST != nil