Skip to content

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

feat(pg): migrate PostgreSQL QuerySpan from ANTLR to omni (#19703)

h3n4le3839236daa3
diff --git a/backend/plugin/parser/pg/query_span.go b/backend/plugin/parser/pg/query_span.go
index 7be22bd7a6..037397ad70 100644
--- a/backend/plugin/parser/pg/query_span.go
+++ b/backend/plugin/parser/pg/query_span.go
@@ -27,9 +27,8 @@ func GetQuerySpan(ctx context.Context, gCtx base.GetQuerySpanContext, stmt base.
if schema != "" {
searchPath = []string{schema}
}
- extractor := newQuerySpanExtractor(database, searchPath, gCtx)
+ extractor := newOmniQuerySpanExtractor(database, searchPath, gCtx)
- // Use the new ANTLR-based implementation
querySpan, err := extractor.getQuerySpan(ctx, stmt.Text)
if err != nil {
return nil, errors.Wrapf(err, "failed to get query span from statement: %s", stmt.Text)
diff --git a/backend/plugin/parser/pg/query_span_omni.go b/backend/plugin/parser/pg/query_span_omni.go
new file mode 100644
index 0000000000..ef2c8fcf5c
--- /dev/null
+++ b/backend/plugin/parser/pg/query_span_omni.go
@@ -0,0 +1,787 @@
+package pg
+
+import (
+ "context"
+
+ "fmt"
+ "strings"
+
+ "github.com/pkg/errors"
+
+ "github.com/bytebase/omni/pg/ast"
+ "github.com/bytebase/omni/pg/catalog"
+ omniparser "github.com/bytebase/omni/pg/parser"
+
+ storepb "github.com/bytebase/bytebase/backend/generated-go/store"
+ "github.com/bytebase/bytebase/backend/plugin/parser/base"
+ "github.com/bytebase/bytebase/backend/store/model"
+)
+
+// omniQuerySpanExtractor extracts query span information using the omni parser
+// and catalog, replacing the ANTLR-based querySpanExtractor.
+type omniQuerySpanExtractor struct {
+ ctx context.Context
+ gCtx base.GetQuerySpanContext
+ defaultDatabase string
+ searchPath []string
+ // metaCache is a lazy-load cache for database metadata.
+ // Use getDatabaseMetadata() instead of accessing directly.
+ metaCache map[string]*model.DatabaseMetadata
+ cat *catalog.Catalog
+}
+
+// newOmniQuerySpanExtractor creates a new omni-based query span extractor.
+func newOmniQuerySpanExtractor(defaultDatabase string, searchPath []string, gCtx base.GetQuerySpanContext) *omniQuerySpanExtractor {
+ if len(searchPath) == 0 {
+ searchPath = []string{"public"}
+ }
+ return &omniQuerySpanExtractor{
+ defaultDatabase: defaultDatabase,
+ searchPath: searchPath,
+ gCtx: gCtx,
+ metaCache: make(map[string]*model.DatabaseMetadata),
+ }
+}
+
+// getDatabaseMetadata returns cached database metadata, fetching it if not yet cached.
+func (e *omniQuerySpanExtractor) getDatabaseMetadata(database string) (*model.DatabaseMetadata, error) {
+ if meta, ok := e.metaCache[database]; ok {
+ return meta, nil
+ }
+ _, meta, err := e.gCtx.GetDatabaseMetadataFunc(e.ctx, e.gCtx.InstanceID, database)
+ if err != nil {
+ return nil, errors.Wrapf(err, "failed to get database metadata for database: %s", database)
+ }
+ e.metaCache[database] = meta
+ return meta, nil
+}
+
+// initCatalog initializes the omni catalog from the database metadata.
+// It generates minimal DDL from the metadata proto and loads it into the catalog.
+// We generate DDL directly here instead of using schema.GetDatabaseDefinition
+// to avoid circular imports (schema/pg imports parser/pg).
+func (e *omniQuerySpanExtractor) initCatalog() error {
+ meta, err := e.getDatabaseMetadata(e.defaultDatabase)
+ if err != nil {
+ return errors.Wrapf(err, "failed to get database metadata for catalog init")
+ }
+
+ e.cat = catalog.New()
+ e.cat.SetSearchPath(e.searchPath)
+
+ if meta == nil {
+ return nil
+ }
+
+ ddl := buildMinimalDDL(meta.GetProto())
+ if ddl != "" {
+ if _, err := e.cat.Exec(ddl, &catalog.ExecOptions{ContinueOnError: true}); err != nil {
+ return errors.Wrapf(err, "failed to load schema DDL into catalog")
+ }
+ }
+
+ return nil
+}
+
+// buildMinimalDDL generates CREATE SCHEMA / CREATE TABLE / CREATE VIEW / CREATE FUNCTION
+// statements from metadata, sufficient for omni's AnalyzeSelectStmt to resolve columns.
+func buildMinimalDDL(meta *storepb.DatabaseSchemaMetadata) string {
+ if meta == nil {
+ return ""
+ }
+ var b strings.Builder
+ for _, s := range meta.Schemas {
+ schemaName := s.Name
+ if schemaName != "public" && schemaName != "pg_catalog" {
+ fmt.Fprintf(&b, "CREATE SCHEMA IF NOT EXISTS %s;\n", quoteIdentifier(schemaName))
+ }
+ for _, t := range s.Tables {
+ buildCreateTable(&b, schemaName, t)
+ }
+ for _, v := range s.Views {
+ buildCreateView(&b, schemaName, v)
+ }
+ for _, v := range s.MaterializedViews {
+ buildCreateMaterializedView(&b, schemaName, v)
+ }
+ for _, f := range s.Functions {
+ if f.Definition != "" {
+ fmt.Fprintf(&b, "%s;\n", strings.TrimSuffix(strings.TrimSpace(f.Definition), ";"))
+ }
+ }
+ }
+ return b.String()
+}
+
+func buildCreateTable(b *strings.Builder, schema string, t *storepb.TableMetadata) {
+ fmt.Fprintf(b, "CREATE TABLE %s.%s (\n", quoteIdentifier(schema), quoteIdentifier(t.Name))
+ for i, c := range t.Columns {
+ colType := c.Type
+ if colType == "" {
+ colType = "text"
+ }
+ fmt.Fprintf(b, " %s %s", quoteIdentifier(c.Name), colType)
+ if i < len(t.Columns)-1 {
+ b.WriteString(",")
+ }
+ b.WriteString("\n")
+ }
+ b.WriteString(");\n")
+}
+
+func buildCreateView(b *strings.Builder, schema string, v *storepb.ViewMetadata) {
+ if v.Definition == "" {
+ return
+ }
+ def := strings.TrimSuffix(strings.TrimSpace(v.Definition), ";")
+ fmt.Fprintf(b, "CREATE VIEW %s.%s AS %s;\n", quoteIdentifier(schema), quoteIdentifier(v.Name), def)
+}
+
+func buildCreateMaterializedView(b *strings.Builder, schema string, v *storepb.MaterializedViewMetadata) {
+ if v.Definition == "" {
+ return
+ }
+ def := strings.TrimSuffix(strings.TrimSpace(v.Definition), ";")
+ fmt.Fprintf(b, "CREATE MATERIALIZED VIEW %s.%s AS %s;\n", quoteIdentifier(schema), quoteIdentifier(v.Name), def)
+}
+
+func quoteIdentifier(name string) string {
+ return `"` + strings.ReplaceAll(name, `"`, `""`) + `"`
+}
+
+// getQuerySpan extracts the query span for the given SQL statement.
+func (e *omniQuerySpanExtractor) getQuerySpan(ctx context.Context, stmt string) (*base.QuerySpan, error) {
+ e.ctx = ctx
+
+ // Step 1: Parse with omni.
+ omniStmts, err := ParsePg(stmt)
+ if err != nil {
+ // Convert omni parse error to *base.SyntaxError with position info
+ // so the SQL service can populate DetailedError.SyntaxError.
+ syntaxErr := &base.SyntaxError{
+ Message: err.Error(),
+ Position: &storepb.Position{Line: 1, Column: 1},
+ }
+ var parseErr *omniparser.ParseError
+ if errors.As(err, &parseErr) && parseErr.Position > 0 {
+ syntaxErr.Position = ByteOffsetToRunePosition(stmt, parseErr.Position-1)
+ }
+ return nil, syntaxErr
+ }
+ if len(omniStmts) != 1 {
+ return nil, errors.Errorf("expected exactly 1 statement, got %d", len(omniStmts))
+ }
+
+ // Step 2: Extract access tables (non-fatal on error — some statement
+ // types like SET don't have table references).
+ accessesMap := make(base.SourceColumnSet)
+ accessTables, err := ExtractAccessTables(stmt, ExtractAccessTablesOption{
+ DefaultDatabase: e.defaultDatabase,
+ DefaultSchema: e.searchPath[0],
+ GetDatabaseMetadata: e.gCtx.GetDatabaseMetadataFunc,
+ Ctx: ctx,
+ InstanceID: e.gCtx.InstanceID,
+ SkipMetadataValidation: false,
+ })
+ if err == nil {
+ for _, resource := range accessTables {
+ accessesMap[resource] = true
+ }
+ }
+
+ // Step 3: Check for mixed system/user tables.
+ allSystems, mixed := isMixedQuery(accessesMap)
+ if mixed {
+ return nil, base.MixUserSystemTablesError
+ }
+
+ // Step 4: Classify query type.
+ queryType, isExplainAnalyze := classifyQueryType(omniStmts[0].AST, allSystems)
+
+ // Step 5: Return early for non-SELECT queries.
+ if queryType != base.Select {
+ return &base.QuerySpan{
+ Type: queryType,
+ SourceColumns: base.SourceColumnSet{},
+ Results: []base.QuerySpanResult{},
+ }, nil
+ }
+
+ // For EXPLAIN ANALYZE SELECT, return with source columns but no results.
+ if isExplainAnalyze {
+ return &base.QuerySpan{
+ Type: queryType,
+ SourceColumns: accessesMap,
+ Results: []base.QuerySpanResult{},
+ }, nil
+ }
+
+ // Step 6: Cast to SelectStmt, init catalog, analyze.
+ selStmt, ok := omniStmts[0].AST.(*ast.SelectStmt)
+ if !ok {
+ // Not a SelectStmt (e.g., SET, SHOW classified as Select type).
+ return &base.QuerySpan{
+ Type: base.Select,
+ SourceColumns: accessesMap,
+ Results: []base.QuerySpanResult{},
+ }, nil
+ }
+
+ // Pre-analysis check: if the parse tree contains constructs that omni
+ // doesn't fully handle (JSON constructors, function calls that may be UDFs),
+ // fall back to ANTLR immediately.
+ if selectNeedsFallback(selStmt) {
+ return e.fallbackToANTLR(ctx, stmt)
+ }
+
+ if err := e.initCatalog(); err != nil {
+ return nil, errors.Wrapf(err, "failed to initialize catalog")
+ }
+
+ query, err := e.cat.AnalyzeSelectStmt(selStmt)
+ if err != nil {
+ // Fallback: use legacy ANTLR-based extractor when omni analysis fails.
+ return e.fallbackToANTLR(ctx, stmt)
+ }
+
+ // Post-analysis check: if the analyzed query has patterns that need
+ // special handling not yet in omni (function RTEs, UDFs).
+ if queryNeedsFallback(query) {
+ return e.fallbackToANTLR(ctx, stmt)
+ }
+
+ // Step 7: Extract lineage from analyzed query.
+ // SourceColumns (table-level access) is already captured in accessesMap
+ // from ExtractAccessTables above — no need to re-extract from the query.
+ results := e.extractLineage(query, selStmt)
+
+ return &base.QuerySpan{
+ Type: base.Select,
+ SourceColumns: accessesMap,
+ Results: results,
+ }, nil
+}
+
+// extractLineage extracts the result column lineage from an analyzed query.
+// selStmt is the original parse tree, used to determine IsPlainField
+// (which is true only for columns that came from * expansion).
+func (e *omniQuerySpanExtractor) extractLineage(q *catalog.Query, selStmt *ast.SelectStmt) []base.QuerySpanResult {
+ // Handle set operations (UNION/INTERSECT/EXCEPT).
+ if q.SetOp != catalog.SetOpNone {
+ return e.extractSetOpLineage(q, selStmt)
+ }
+
+ // Build a plain-field mask from the parse tree's target list.
+ // IsPlainField = true only for columns expanded from SELECT * or SELECT t.*.
+ plainMask := buildPlainFieldMask(selStmt, q)
+
+ var results []base.QuerySpanResult
+ idx := 0
+ for _, te := range q.TargetList {
+ if te.ResJunk {
+ continue
+ }
+ sourceColSet := make(base.SourceColumnSet)
+ e.walkExpr(q, te.Expr, sourceColSet)
+ isPlain := idx < len(plainMask) && plainMask[idx]
+ // Even if the parse tree says this came from *, the underlying
+ // expression through CTEs/subqueries may not be a simple column ref.
+ if isPlain {
+ isPlain = isUltimatelyPlainColumn(q, te.Expr)
+ }
+ results = append(results, base.QuerySpanResult{
+ Name: te.ResName,
+ SourceColumns: sourceColSet,
+ IsPlainField: isPlain,
+ })
+ idx++
+ }
+ return results
+}
+
+// isUltimatelyPlainColumn checks whether an expression, after resolving through
+// CTEs and subqueries, is a simple column reference (VarExpr pointing to a
+// physical table). Aggregates, functions, and other expressions return false.
+func isUltimatelyPlainColumn(q *catalog.Query, expr catalog.AnalyzedExpr) bool {
+ if expr == nil {
+ return false
+ }
+ v, ok := expr.(*catalog.VarExpr)
+ if !ok {
+ return false
+ }
+ if v.RangeIdx < 0 || v.RangeIdx >= len(q.RangeTable) {
+ return false
+ }
+ rte := q.RangeTable[v.RangeIdx]
+ colIdx := int(v.AttNum - 1)
+
+ switch rte.Kind {
+ case catalog.RTERelation:
+ return true
+ case catalog.RTESubquery:
+ if rte.Subquery != nil && colIdx >= 0 && colIdx < len(rte.Subquery.TargetList) {
+ return isUltimatelyPlainColumn(rte.Subquery, rte.Subquery.TargetList[colIdx].Expr)
+ }
+ case catalog.RTECTE:
+ if rte.CTEIndex >= 0 && rte.CTEIndex < len(q.CTEList) {
+ cte := q.CTEList[rte.CTEIndex]
+ if cte.Query != nil && colIdx >= 0 && colIdx < len(cte.Query.TargetList) {
+ return isUltimatelyPlainColumn(cte.Query, cte.Query.TargetList[colIdx].Expr)
+ }
+ }
+ default:
+ return false
+ }
+ return false
+}
+
+// buildPlainFieldMask returns a boolean slice aligned with the analyzed
+// query's non-junk TargetList. An entry is true if the column was produced
+// by * expansion (SELECT * or SELECT t.*), false for explicit column refs.
+func buildPlainFieldMask(selStmt *ast.SelectStmt, q *catalog.Query) []bool {
+ // Collect non-junk target entries.
+ var targets []*catalog.TargetEntry
+ for _, te := range q.TargetList {
+ if !te.ResJunk {
+ targets = append(targets, te)
+ }
+ }
+ nResults := len(targets)
+
+ if selStmt == nil || selStmt.TargetList == nil {
+ return make([]bool, nResults)
+ }
+
+ // Count parse-tree items (stars and non-stars).
+ var parseTargets []*ast.ResTarget
+ for _, item := range selStmt.TargetList.Items {
+ if rt, ok := item.(*ast.ResTarget); ok {
+ parseTargets = append(parseTargets, rt)
+ }
+ }
+
+ // For each star, determine how many columns it expands to by
+ // looking at the table it references and counting columns in that RTE.
+ mask := make([]bool, nResults)
+ pos := 0
+
+ for _, rt := range parseTargets {
+ if pos >= nResults {
+ break
+ }
+ if isStarTarget(rt) {
+ tableName := starTableName(rt)
+ starCount := countStarColumnsFromRTE(q, targets, pos, tableName)
+ for i := 0; i < starCount && pos < nResults; i++ {
+ mask[pos] = true
+ pos++
+ }
+ } else {
+ mask[pos] = false
+ pos++
+ }
+ }
+
+ return mask
+}
+
+// isStarTarget checks if a ResTarget in the parse tree is a star expression
+// (SELECT * or SELECT t.*).
+func isStarTarget(rt *ast.ResTarget) bool {
+ if rt == nil || rt.Val == nil {
+ return false
+ }
+ cr, ok := rt.Val.(*ast.ColumnRef)
+ if !ok || cr.Fields == nil || len(cr.Fields.Items) == 0 {
+ return false
+ }
+ last := cr.Fields.Items[len(cr.Fields.Items)-1]
+ _, isStar := last.(*ast.A_Star)
+ return isStar
+}
+
+// starTableName extracts the table qualifier from a star target.
+// For "SELECT *" returns "", for "SELECT t.*" returns "t".
+func starTableName(rt *ast.ResTarget) string {
+ cr, ok := rt.Val.(*ast.ColumnRef)
+ if !ok || cr.Fields == nil {
+ return ""
+ }
+ // For t.*, Fields = [String("t"), A_Star{}]
+ if len(cr.Fields.Items) >= 2 {
+ if s, ok := cr.Fields.Items[0].(*ast.String); ok {
+ return s.Str
+ }
+ }
+ return ""
+}
+
+// countStarColumnsFromRTE counts how many analyzed target entries starting
+// at pos belong to a star expansion. For unqualified * (tableName=""), it
+// counts entries that share the same contiguous RangeIdx sequence covering
+// all non-join RTEs. For qualified t.* (tableName="t"), it counts entries
+// whose RTE ERef matches the table name.
+func countStarColumnsFromRTE(q *catalog.Query, targets []*catalog.TargetEntry, startPos int, tableName string) int {
+ if startPos >= len(targets) {
+ return 0
+ }
+
+ if tableName != "" {
+ // Qualified star: count consecutive entries from the named RTE.
+ count := 0
+ for i := startPos; i < len(targets); i++ {
+ v, ok := targets[i].Expr.(*catalog.VarExpr)
+ if !ok {
+ break
+ }
+ if v.RangeIdx < 0 || v.RangeIdx >= len(q.RangeTable) {
+ break
+ }
+ rte := q.RangeTable[v.RangeIdx]
+ if rte.ERef != tableName && rte.Alias != tableName {
+ break
+ }
+ count++
+ }
+ if count == 0 {
+ return 1
+ }
+ return count
+ }
+
+ // Unqualified star: expands all non-join RTEs in FROM order.
+ // Count how many consecutive VarExprs follow the expected star expansion pattern.
+ count := 0
+ for i := startPos; i < len(targets); i++ {
+ v, ok := targets[i].Expr.(*catalog.VarExpr)
+ if !ok {
+ break
+ }
+ if v.RangeIdx < 0 || v.RangeIdx >= len(q.RangeTable) {
+ break
+ }
+ rte := q.RangeTable[v.RangeIdx]
+ if rte.Kind == catalog.RTEJoin {
+ break
+ }
+ // Check if this column's AttNum is sequential within its RTE.
+ // Star expansion produces columns in order: attnum 1, 2, 3, ...
+ if count > 0 {
+ if prev, ok := targets[i-1].Expr.(*catalog.VarExpr); ok && v.RangeIdx == prev.RangeIdx && v.AttNum != prev.AttNum+1 {
+ break
+ }
+ }
+ count++
+ }
+ if count == 0 {
+ return 1
+ }
+ return count
+}
+
+// extractSetOpLineage handles UNION/INTERSECT/EXCEPT by merging lineage from both branches.
+func (e *omniQuerySpanExtractor) extractSetOpLineage(q *catalog.Query, selStmt *ast.SelectStmt) []base.QuerySpanResult {
+ if q.LArg == nil || q.RArg == nil {
+ return nil
+ }
+ lResults := e.extractLineage(q.LArg, selStmt.Larg)
+ rResults := e.extractLineage(q.RArg, selStmt.Rarg)
+
+ // For EXCEPT, output rows come only from the left branch — do not
+ // merge right-side lineage into the result columns.
+ includeRight := q.SetOp != catalog.SetOpExcept && q.SetOp != catalog.SetOpExceptAll
+
+ var results []base.QuerySpanResult
+ for i, lr := range lResults {
+ merged := make(base.SourceColumnSet)
+ for col := range lr.SourceColumns {
+ merged[col] = true
+ }
+ if includeRight && i < len(rResults) {
+ for col := range rResults[i].SourceColumns {
+ merged[col] = true
+ }
+ }
+ results = append(results, base.QuerySpanResult{
+ Name: lr.Name,
+ SourceColumns: merged,
+ IsPlainField: false, // set-op results are never plain fields
+ })
+ }
+ return results
+}
+
+// walkExpr recursively walks an analyzed expression tree and collects all
+// source column references into the result set.
+func (e *omniQuerySpanExtractor) walkExpr(q *catalog.Query, expr catalog.AnalyzedExpr, result base.SourceColumnSet) {
+ if expr == nil {
+ return
+ }
+ switch v := expr.(type) {
+ case *catalog.VarExpr:
+ e.resolveVar(q, v, result)
+ case *catalog.FuncCallExpr:
+ for _, arg := range v.Args {
+ e.walkExpr(q, arg, result)
+ }
+ case *catalog.AggExpr:
+ for _, arg := range v.Args {
+ e.walkExpr(q, arg, result)
+ }
+ case *catalog.OpExpr:
+ e.walkExpr(q, v.Left, result)
+ e.walkExpr(q, v.Right, result)
+ case *catalog.BoolExprQ:
+ for _, arg := range v.Args {
+ e.walkExpr(q, arg, result)
+ }
+ case *catalog.CaseExprQ:
+ e.walkExpr(q, v.Arg, result)
+ for _, w := range v.When {
+ e.walkExpr(q, w.Condition, result)
+ e.walkExpr(q, w.Result, result)
+ }
+ e.walkExpr(q, v.Default, result)
+ case *catalog.CoalesceExprQ:
+ for _, arg := range v.Args {
+ e.walkExpr(q, arg, result)
+ }
+ case *catalog.SubLinkExpr:
+ e.walkExpr(q, v.TestExpr, result)
+ if v.SubQuery != nil {
+ for _, te := range v.SubQuery.TargetList {
+ if !te.ResJunk {
+ e.walkExpr(v.SubQuery, te.Expr, result)
+ }
+ }
+ }
+ case *catalog.RelabelExpr:
+ e.walkExpr(q, v.Arg, result)
+ case *catalog.CoerceViaIOExpr:
+ e.walkExpr(q, v.Arg, result)
+ case *catalog.RowExprQ:
+ for _, arg := range v.Args {
+ e.walkExpr(q, arg, result)
+ }
+ case *catalog.WindowFuncExpr:
+ for _, arg := range v.Args {
+ e.walkExpr(q, arg, result)
+ }
+ e.walkExpr(q, v.AggFilter, result)
+ case *catalog.NullIfExprQ:
+ for _, arg := range v.Args {
+ e.walkExpr(q, arg, result)
+ }
+ case *catalog.MinMaxExprQ:
+ for _, arg := range v.Args {
+ e.walkExpr(q, arg, result)
+ }
+ case *catalog.ArrayExprQ:
+ for _, elem := range v.Elements {
+ e.walkExpr(q, elem, result)
+ }
+ case *catalog.ScalarArrayOpExpr:
+ e.walkExpr(q, v.Left, result)
+ e.walkExpr(q, v.Right, result)
+ case *catalog.CollateExprQ:
+ e.walkExpr(q, v.Arg, result)
+ case *catalog.NullTestExpr:
+ e.walkExpr(q, v.Arg, result)
+ case *catalog.BooleanTestExpr:
+ e.walkExpr(q, v.Arg, result)
+ case *catalog.DistinctExprQ:
+ e.walkExpr(q, v.Left, result)
+ e.walkExpr(q, v.Right, result)
+ case *catalog.FieldSelectExprQ:
+ e.walkExpr(q, v.Arg, result)
+ // ConstExpr, SQLValueFuncExpr, CoerceToDomainValueExpr — no column refs.
+ default:
+ }
+}
+
+// resolveVar resolves a VarExpr to its ultimate source column(s).
+func (e *omniQuerySpanExtractor) resolveVar(q *catalog.Query, v *catalog.VarExpr, result base.SourceColumnSet) {
+ if v.RangeIdx < 0 || v.RangeIdx >= len(q.RangeTable) {
+ return
+ }
+ rte := q.RangeTable[v.RangeIdx]
+ colIdx := int(v.AttNum - 1) // AttNum is 1-based
+
+ switch rte.Kind {
+ case catalog.RTERelation:
+ rel := e.cat.GetRelationByOID(rte.RelOID)
+ if rel == nil || rel.Schema == nil {
+ return
+ }
+ colName := ""
+ if colIdx >= 0 && colIdx < len(rte.ColNames) {
+ colName = rte.ColNames[colIdx]
+ }
+ result[base.ColumnResource{
+ Database: e.defaultDatabase,
+ Schema: rel.Schema.Name,
+ Table: rel.Name,
+ Column: colName,
+ }] = true
+
+ case catalog.RTESubquery:
+ if rte.Subquery == nil {
+ return
+ }
+ if colIdx >= 0 && colIdx < len(rte.Subquery.TargetList) {
+ te := rte.Subquery.TargetList[colIdx]
+ e.walkExpr(rte.Subquery, te.Expr, result)
+ }
+
+ case catalog.RTECTE:
+ if rte.CTEIndex >= 0 && rte.CTEIndex < len(q.CTEList) {
+ cte := q.CTEList[rte.CTEIndex]
+ if cte.Query != nil && colIdx >= 0 && colIdx < len(cte.Query.TargetList) {
+ te := cte.Query.TargetList[colIdx]
+ e.walkExpr(cte.Query, te.Expr, result)
+ }
+ }
+
+ case catalog.RTEJoin:
+ // After analysis, VarExprs typically point to base RTEs, not join RTEs.
+
+ case catalog.RTEFunction:
+ // Function results have no further lineage to track.
+
+ default:
+ // Unknown RTE kind — skip.
+ }
+}
+
+// selectNeedsFallback checks the raw parse tree (before analysis) for constructs
+// that omni doesn't handle well, such as JSON constructors and function calls.
+func selectNeedsFallback(sel *ast.SelectStmt) bool {
+ if sel == nil {
+ return false
+ }
+ // Check set operations recursively.
+ if sel.Larg != nil && selectNeedsFallback(sel.Larg) {
+ return true
+ }
+ if sel.Rarg != nil && selectNeedsFallback(sel.Rarg) {
+ return true
+ }
+ // Check target list for unsupported expressions.
+ if sel.TargetList != nil {
+ for _, item := range sel.TargetList.Items {
+ if rt, ok := item.(*ast.ResTarget); ok && rt.Val != nil {
+ if astNodeNeedsFallback(rt.Val) {
+ return true
+ }
+ }
+ }
+ }
+ // Check FROM clause for function tables.
+ if sel.FromClause != nil {
+ for _, item := range sel.FromClause.Items {
+ if _, ok := item.(*ast.RangeFunction); ok {
+ return true
+ }
+ }
+ }
+ return false
+}
+
+// astNodeNeedsFallback checks if an AST node contains constructs that require
+// fallback to ANTLR (e.g., JSON constructors, function calls that may be UDFs).
+func astNodeNeedsFallback(n ast.Node) bool {
+ if n == nil {
+ return false
+ }
+ switch v := n.(type) {
+ case *ast.JsonObjectConstructor, *ast.JsonArrayConstructor, *ast.JsonArrayQueryConstructor,
+ *ast.JsonFuncExpr:
+ return true
+ case *ast.FuncCall:
+ // Function calls may be UDFs needing body analysis.
+ return true
+ case *ast.A_Indirection:
+ // Array subscripts and field selections — omni may reduce to ConstExpr.
+ return true
+ case *ast.SubLink:
+ if sel, ok := v.Subselect.(*ast.SelectStmt); ok {
+ return selectNeedsFallback(sel)
+ }
+ default:
+ // Other node types don't need fallback.
+ }
+ return false
+}
+
+// queryNeedsFallback checks if the analyzed query contains patterns that
+// omni may not handle correctly and should fall back to ANTLR.
+// This includes: function table sources, function calls in expressions
+// (which may be UDFs needing body analysis), and nil expressions
+// (indicating omni didn't fully resolve something).
+func queryNeedsFallback(q *catalog.Query) bool {
+ for _, rte := range q.RangeTable {
+ if rte.Kind == catalog.RTEFunction {
+ return true
+ }
+ }
+ for _, te := range q.TargetList {
+ if te.ResJunk {
+ continue
+ }
+ if exprNeedsFallback(te.Expr) {
+ return true
+ }
+ }
+ return false
+}
+
+func exprNeedsFallback(expr catalog.AnalyzedExpr) bool {
+ if expr == nil {
+ // nil expression means omni didn't resolve it.
+ return true
+ }
+ switch v := expr.(type) {
+ case *catalog.FuncCallExpr:
+ // Any function call may be a UDF needing body analysis.
+ return true
+ case *catalog.AggExpr:
+ // Aggregate calls are handled by omni, but some JSON/custom aggregates
+ // may produce incorrect results — skip for now, will revisit.
+ return false
+ case *catalog.OpExpr:
+ return exprNeedsFallback(v.Left) || exprNeedsFallback(v.Right)
+ case *catalog.CaseExprQ:
+ if exprNeedsFallback(v.Arg) || exprNeedsFallback(v.Default) {
+ return true
+ }
+ for _, w := range v.When {
+ if exprNeedsFallback(w.Condition) || exprNeedsFallback(w.Result) {
+ return true
+ }
+ }
+ case *catalog.CoalesceExprQ:
+ for _, arg := range v.Args {
+ if exprNeedsFallback(arg) {
+ return true
+ }
+ }
+ case *catalog.SubLinkExpr:
+ if v.SubQuery != nil {
+ return queryNeedsFallback(v.SubQuery)
+ }
+ case *catalog.RelabelExpr:
+ return exprNeedsFallback(v.Arg)
+ case *catalog.CoerceViaIOExpr:
+ return exprNeedsFallback(v.Arg)
+ default:
+ // Other expression types don't need fallback.
+ }
+ return false
+}
+
+// fallbackToANTLR uses the legacy ANTLR-based extractor when omni analysis fails.
+func (e *omniQuerySpanExtractor) fallbackToANTLR(ctx context.Context, stmt string) (*base.QuerySpan, error) {
+ legacy := newQuerySpanExtractor(e.defaultDatabase, e.searchPath, e.gCtx)
+ return legacy.getQuerySpan(ctx, stmt)
+}
diff --git a/docs/plans/2026-03-24-pg-query-span-omni-migration.md b/docs/plans/2026-03-24-pg-query-span-omni-migration.md
new file mode 100644
index 0000000000..5ed9b35189
--- /dev/null
+++ b/docs/plans/2026-03-24-pg-query-span-omni-migration.md
@@ -0,0 +1,618 @@
+# PostgreSQL QuerySpan Migration to Omni Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Replace the ANTLR-based PostgreSQL QuerySpan extraction (~3,868 lines) with omni's semantic analysis infrastructure, reducing code by ~80% while maintaining full test compatibility with the existing 46 query_span + 31 query_type YAML test cases.
+
+**Architecture:** The new implementation uses omni's `Catalog.AnalyzeSelectStmt()` to produce a semantically analyzed `Query` struct (with resolved column references, type information, and provenance tracking), then walks the analyzed tree to extract column lineage. Schema metadata is loaded into omni's catalog via `schema.GetDatabaseDefinition() → catalog.Exec(schemaDDL)`, reusing the pattern already established in `walk_through_omni.go`.
+
+**Tech Stack:** Go, omni (`github.com/bytebase/omni/pg/catalog`), existing bytebase metadata infrastructure
+
+**Scope exclusion:** PL/pgSQL function body analysis is tracked separately in [BYT-9082](https://linear.app/bytebase/issue/BYT-9082). This plan defers to that issue for function body parsing. During migration, function calls will fall back to the existing ANTLR-based function analysis until BYT-9082 is complete.
+
+---
+
+## Background
+
+### Current state
+- `query_span.go` — Entry point, calls ANTLR-based extractor
+- `query_span_extractor.go` — 3,868 lines of ANTLR tree walking (~70 methods)
+- `access_tables_antlr.go` — ANTLR listener for extracting accessed tables
+- `query_type.go` — Already migrated to omni AST (no work needed)
+- `access_tables.go` — Already has omni-based `ExtractAccessTables()` (no work needed)
+
+### Target state
+- `query_span.go` — Entry point calls omni-based extractor
+- `query_span_omni.go` — New file: ~400-600 lines using omni's `AnalyzeSelectStmt()` + lineage walker
+- `access_tables_antlr.go` — Deleted (replaced by existing `access_tables.go`)
+- `query_span_extractor.go` — Deleted after migration complete
+
+### Key files to read before starting
+- `omni/pg/catalog/query.go` — Query, TargetEntry, VarExpr, RangeTableEntry types
+- `omni/pg/catalog/analyze.go` — `AnalyzeSelectStmt()` (line 3580) and internal `analyzeSelectStmt()`
+- `omni/pg/catalog/query_span_test.go` — Proof-of-concept lineage walker (our verification test)
+- `bytebase/backend/plugin/schema/pg/walk_through_omni.go` — Pattern for loading metadata into omni catalog
+- `bytebase/backend/plugin/schema/pg/get_database_definition.go` — Generates DDL from metadata proto
+- `bytebase/backend/plugin/parser/pg/query_span_extractor.go` — What we're replacing
+- `bytebase/backend/plugin/parser/pg/test-data/query_span.yaml` — 46 test cases (golden data)
+- `bytebase/backend/plugin/parser/pg/test-data/query_type.yaml` — 31 test cases (already passing)
+
+---
+
+## Task 1: Create the omni-based QuerySpan extractor scaffold
+
+**Files:**
+- Create: `bytebase/backend/plugin/parser/pg/query_span_omni.go`
+- Modify: `bytebase/backend/plugin/parser/pg/query_span.go`
+
+This task creates the new extractor struct and wires up the entry point. The new extractor will use omni's catalog for analysis instead of ANTLR tree walking.
+
+**Step 1: Write the new extractor struct and constructor**
+
+Create `query_span_omni.go` with:
+
+```go
+package pg
+
+import (
+ "context"
+
+ "github.com/pkg/errors"
+
+ "github.com/bytebase/omni/pg/ast"
+ "github.com/bytebase/omni/pg/catalog"
+
+ storepb "github.com/bytebase/bytebase/backend/generated-go/store"
+ "github.com/bytebase/bytebase/backend/plugin/parser/base"
+ "github.com/bytebase/bytebase/backend/plugin/schema"
+ "github.com/bytebase/bytebase/backend/store/model"
+)
+
+// omniQuerySpanExtractor extracts query span using omni's semantic analysis.
+type omniQuerySpanExtractor struct {
+ ctx context.Context
+ gCtx base.GetQuerySpanContext
+ defaultDatabase string
+ searchPath []string
+ metaCache map[string]*model.DatabaseMetadata
+ cat *catalog.Catalog
+}
+
+func newOmniQuerySpanExtractor(
+ defaultDatabase string,
+ searchPath []string,
+ gCtx base.GetQuerySpanContext,
+) *omniQuerySpanExtractor {
+ if len(searchPath) == 0 {
+ searchPath = []string{"public"}
+ }
+ return &omniQuerySpanExtractor{
+ defaultDatabase: defaultDatabase,
+ searchPath: searchPath,
+ gCtx: gCtx,
+ metaCache: make(map[string]*model.DatabaseMetadata),
+ }
+}
+```
+
+**Step 2: Wire up the entry point**
+
+Modify `query_span.go` to call the new extractor. For now, keep both paths and add a feature flag or simply replace:
+
+```go
+func GetQuerySpan(ctx context.Context, gCtx base.GetQuerySpanContext, stmt base.Statement, database, schema string, _ bool) (*base.QuerySpan, error) {
+ if gCtx.GetDatabaseMetadataFunc == nil {
+ return nil, errors.New("GetDatabaseMetadataFunc is not set")
+ }
+ _, meta, err := gCtx.GetDatabaseMetadataFunc(ctx, gCtx.InstanceID, database)
+ if err != nil {
+ return nil, errors.Wrapf(err, "failed to get database metadata for database %q", database)
+ }
+ searchPath := meta.GetSearchPath()
+ if schema != "" {
+ searchPath = []string{schema}
+ }
+ extractor := newOmniQuerySpanExtractor(database, searchPath, gCtx)
+ return extractor.getQuerySpan(ctx, stmt.Text)
+}
+```
+
+**Step 3: Run query_type tests (should still pass since they use omni already)**
+
+Run: `go test -v -count=1 -run ^TestGetQuerySpan$ github.com/bytebase/bytebase/backend/plugin/parser/pg`
+Expected: Tests will fail since `getQuerySpan` is not yet implemented — that's OK.
+
+**Step 4: Commit**
+
+```bash
+git add bytebase/backend/plugin/parser/pg/query_span_omni.go bytebase/backend/plugin/parser/pg/query_span.go
+git commit -m "feat(pg): scaffold omni-based QuerySpan extractor"
+```
+
+---
+
+## Task 2: Implement catalog loading from metadata
+
+**Files:**
+- Modify: `bytebase/backend/plugin/parser/pg/query_span_omni.go`
+
+This task implements loading database schema metadata into omni's catalog, reusing the existing `GetDatabaseDefinition → catalog.Exec` pattern from `walk_through_omni.go`.
+
+**Step 1: Add catalog initialization method**
+
+```go
+func (e *omniQuerySpanExtractor) getDatabaseMetadata(database string) (*model.DatabaseMetadata, error) {
+ if meta, ok := e.metaCache[database]; ok {
+ return meta, nil
+ }
+ _, meta, err := e.gCtx.GetDatabaseMetadataFunc(e.ctx, e.gCtx.InstanceID, database)
+ if err != nil {
+ return nil, errors.Wrapf(err, "failed to get database metadata for database: %s", database)
+ }
+ e.metaCache[database] = meta
+ return meta, nil
+}
+
+// initCatalog creates an omni catalog loaded with the database schema.
+func (e *omniQuerySpanExtractor) initCatalog() error {
+ meta, err := e.getDatabaseMetadata(e.defaultDatabase)
+ if err != nil {
+ return err
+ }
+
+ schemaDDL, err := schema.GetDatabaseDefinition(
+ storepb.Engine_POSTGRES,
+ schema.GetDefinitionContext{},
+ meta.GetProto(),
+ )
+ if err != nil {
+ return errors.Wrap(err, "failed to generate schema DDL")
+ }
+
+ e.cat = catalog.New()
+ e.cat.SetSearchPath(e.searchPath)
+
+ if schemaDDL != "" {
+ if _, err := e.cat.Exec(schemaDDL, &catalog.ExecOptions{ContinueOnError: true}); err != nil {
+ return errors.Wrap(err, "failed to load schema into catalog")
+ }
+ }
+ return nil
+}
+```
+
+**Step 2: Write a test that verifies catalog loading**
+
+Add to a new test file or inline: create metadata proto, call `initCatalog()`, verify a table can be found via `cat.GetRelation("public", "t")`.
+
+**Step 3: Run the test**
+
+Run: `go test -v -count=1 -run ^TestOmniCatalogLoading$ github.com/bytebase/bytebase/backend/plugin/parser/pg`
+Expected: PASS
+
+**Step 4: Commit**
+
+```bash
+git add bytebase/backend/plugin/parser/pg/query_span_omni.go
+git commit -m "feat(pg): implement catalog loading from metadata for QuerySpan"
+```
+
+---
+
+## Task 3: Implement the core getQuerySpan pipeline
+
+**Files:**
+- Modify: `bytebase/backend/plugin/parser/pg/query_span_omni.go`
+
+This is the main pipeline: parse → classify query type → analyze SELECT → extract lineage.
+
+**Step 1: Implement getQuerySpan**
+
+```go
+func (e *omniQuerySpanExtractor) getQuerySpan(ctx context.Context, stmt string) (*base.QuerySpan, error) {
+ e.ctx = ctx
+
+ // Step 1: Parse with omni.
+ omniStmts, err := ParsePg(stmt)
+ if err != nil {
+ return nil, errors.Wrap(err, "failed to parse statement")
+ }
+ if len(omniStmts) != 1 {
+ return nil, errors.Errorf("expected 1 statement, got %d", len(omniStmts))
+ }
+
+ // Step 2: Extract accessed tables using omni (already migrated).
+ accessTables, err := ExtractAccessTables(stmt)
+ if err != nil {
+ return nil, err
+ }
+ accessesMap := make(base.SourceColumnSet)
+ for _, resource := range accessTables {
+ accessesMap[resource] = true
+ }
+
+ // Step 3: Check for mixed system/user tables.
+ allSystems, mixed := isMixedQuery(accessesMap)
+ if mixed {
+ return nil, base.MixUserSystemTablesError
+ }
+
+ // Step 4: Classify query type (already uses omni).
+ queryType, isExplainAnalyze := classifyQueryType(omniStmts[0].AST, allSystems)
+
+ if queryType != base.Select {
+ return &base.QuerySpan{
+ Type: queryType,
+ SourceColumns: base.SourceColumnSet{},
+ Results: []base.QuerySpanResult{},
+ }, nil
+ }
+
+ if isExplainAnalyze {
+ return &base.QuerySpan{
+ Type: queryType,
+ SourceColumns: accessesMap,
+ Results: []base.QuerySpanResult{},
+ }, nil
+ }
+
+ // Step 5: Initialize catalog and analyze SELECT.
+ selStmt, ok := omniStmts[0].AST.(*ast.SelectStmt)
+ if !ok {
+ // Not a SELECT — should not happen after queryType check.
+ return &base.QuerySpan{
+ Type: base.Select,
+ SourceColumns: accessesMap,
+ Results: []base.QuerySpanResult{},
+ }, nil
+ }
+
+ if err := e.initCatalog(); err != nil {
+ return nil, errors.Wrap(err, "failed to init catalog")
+ }
+
+ query, err := e.cat.AnalyzeSelectStmt(selStmt)
+ if err != nil {
+ // Graceful degradation: return what we have.
+ return &base.QuerySpan{
+ Type: base.Select,
+ SourceColumns: accessesMap,
+ Results: []base.QuerySpanResult{},
+ }, nil
+ }
+
+ // Step 6: Extract lineage from analyzed query.
+ results := e.extractLineage(query)
+ allSourceCols := e.extractAllSourceColumns(query)
+ for col := range allSourceCols {
+ accessesMap[col] = true
+ }
+
+ return &base.QuerySpan{
+ Type: base.Select,
+ SourceColumns: accessesMap,
+ Results: results,
+ }, nil
+}
+```
+
+**Step 2: Add stub methods for extractLineage and extractAllSourceColumns**
+
+Return empty results for now — they will be implemented in the next tasks.
+
+**Step 3: Run the query_type tests (31 tests)**
+
+Run: `go test -v -count=1 -run ^TestGetQuerySpan$ github.com/bytebase/bytebase/backend/plugin/parser/pg`
+Expected: query_type tests PASS (they don't check results), query_span tests FAIL (lineage not yet extracted)
+
+**Step 4: Commit**
+
+```bash
+git add bytebase/backend/plugin/parser/pg/query_span_omni.go
+git commit -m "feat(pg): implement core getQuerySpan pipeline with omni"
+```
+
+---
+
+## Task 4: Implement the column lineage walker
+
+**Files:**
+- Modify: `bytebase/backend/plugin/parser/pg/query_span_omni.go`
+
+Port the lineage walker from `omni/pg/catalog/query_span_test.go` into production code, adapted to produce `base.QuerySpanResult` instead of test-only types.
+
+**Step 1: Implement extractLineage**
+
+This walks `Query.TargetList` and for each `TargetEntry`, collects the source `ColumnResource` set by walking the expression tree. The key mapping is:
+
+- `VarExpr` → resolve through `RangeTable[RangeIdx]` to get schema/table/column
+- `RTERelation` → look up `Catalog.GetRelationByOID()` → `Relation.Schema.Name` + `Relation.Name`
+- `RTESubquery` → recurse into `Subquery.TargetList[colIdx]`
+- `RTECTE` → recurse into `CTEList[CTEIndex].Query.TargetList[colIdx]`
+- `RTERelation` with `RelKind='v'` (view) → recurse into `Relation.AnalyzedQuery` (Gap 1 fix)
+
+Key differences from the test walker:
+- Output `base.QuerySpanResult` with `Name`, `SourceColumns` (as `base.SourceColumnSet`), `IsPlainField`
+- Use `e.defaultDatabase` for the `Database` field in `ColumnResource`
+- Handle set operations: merge lineage from `Query.LArg` and `Query.RArg`
+
+**Step 2: Implement extractAllSourceColumns**
+
+Walk the entire Query (TargetList + JoinTree.Quals + JoinExprNode.Quals + HavingQual) to collect all accessed columns. Return as `base.SourceColumnSet`.
+
+**Step 3: Run a subset of query_span tests**
+
+Run: `go test -v -count=1 -run ^TestGetQuerySpan$ github.com/bytebase/bytebase/backend/plugin/parser/pg`
+Expected: Simple tests (column refs, star expansion, JOINs, subqueries, CTEs) should start passing.
+
+**Step 4: Commit**
+
+```bash
+git add bytebase/backend/plugin/parser/pg/query_span_omni.go
+git commit -m "feat(pg): implement column lineage walker for omni QuerySpan"
+```
+
+---
+
+## Task 5: Handle set operations (UNION/INTERSECT/EXCEPT)
+
+**Files:**
+- Modify: `bytebase/backend/plugin/parser/pg/query_span_omni.go`
+
+Set operations produce a top-level `Query` with `SetOp != SetOpNone` and `LArg`/`RArg` branches. The top-level `TargetList` has placeholder `VarExpr` entries without real provenance. We need to merge lineage from both branches.
+
+**Step 1: Add set operation handling to extractLineage**
+
+When `query.SetOp != catalog.SetOpNone`:
+- Recursively get lineage from `query.LArg` and `query.RArg`
+- For each output column position, merge source columns from both branches
+- Column names come from the left branch (PG convention)
+- For EXCEPT: only include left branch sources (right branch filters, doesn't contribute to output)
+
+**Step 2: Run tests with UNION/INTERSECT/EXCEPT cases**
+
+Expected: Set operation test cases pass.
+
+**Step 3: Commit**
+
+```bash
+git commit -m "feat(pg): handle set operations in omni QuerySpan lineage"
+```
+
+---
+
+## Task 6: Handle view through-lineage
+
+**Files:**
+- Modify: `bytebase/backend/plugin/parser/pg/query_span_omni.go`
+
+When `resolveVar` encounters an `RTERelation` where the underlying `Relation.RelKind == 'v'` (view), it should recurse into `Relation.AnalyzedQuery` to trace lineage to the base tables.
+
+**Step 1: Extend resolveVar for views**
+
+In the `RTERelation` case of `resolveVar`:
+```go
+case catalog.RTERelation:
+ rel := e.cat.GetRelationByOID(rte.RelOID)
+ if rel == nil || rel.Schema == nil {
+ return
+ }
+ // View through-lineage: recurse into view definition.
+ if rel.RelKind == 'v' && rel.AnalyzedQuery != nil {
+ if colIdx >= 0 && colIdx < len(rel.AnalyzedQuery.TargetList) {
+ te := rel.AnalyzedQuery.TargetList[colIdx]
+ e.walkExpr(rel.AnalyzedQuery, te.Expr, seen, result)
+ }
+ return
+ }
+ // Physical table: terminal case.
+ // ... existing code ...
+```
+
+Also handle materialized views (`RelKind == 'm'`) the same way.
+
+**Step 2: Run view-related test cases**
+
+Expected: View lineage traces through to base tables.
+
+**Step 3: Commit**
+
+```bash
+git commit -m "feat(pg): implement view through-lineage in omni QuerySpan"
+```
+
+---
+
+## Task 7: Handle system functions as table sources
+
+**Files:**
+- Modify: `bytebase/backend/plugin/parser/pg/query_span_omni.go`
+
+Omni's analyzer handles system functions in FROM clause via `RTEFunction`. However, the column names for system functions may differ from what QuerySpan expects. The key system functions are:
+
+- `generate_series` → single column "generate_series"
+- `generate_subscripts` → single column "generate_subscripts"
+- `unnest` → N columns of "unnest" (one per array argument)
+- `jsonb_each`/`json_each` → "key", "value"
+- `jsonb_array_elements`/`json_array_elements` → "value"
+- `json_to_record`/`jsonb_to_record` → columns from alias clause
+- `json_to_recordset`/`jsonb_to_recordset` → columns from alias clause
+
+**Step 1: Verify how omni handles these in RTEFunction**
+
+Read `omni/pg/catalog/analyze.go` to check how `transformRangeFunction` creates RTEs for these functions. The column names should already be set correctly by omni's analysis.
+
+**Step 2: If omni handles column names correctly, no code needed**
+
+For `RTEFunction`, the lineage walker already returns no source columns (function results have no base-table provenance). The column names come from `rte.ColNames`. Verify by running the unnest/generate_series test cases.
+
+**Step 3: If adjustments needed, add special handling**
+
+Only add code if test cases fail — omni likely already handles the column names.
+
+**Step 4: Run system function test cases**
+
+Run: `go test -v -count=1 -run ^TestGetQuerySpan$ github.com/bytebase/bytebase/backend/plugin/parser/pg`
+Expected: unnest, generate_series, json function tests pass.
+
+**Step 5: Commit**
+
+```bash
+git commit -m "feat(pg): handle system function table sources in omni QuerySpan"
+```
+
+---
+
+## Task 8: Handle user-defined functions (bridge to ANTLR for BYT-9082)
+
+**Files:**
+- Modify: `bytebase/backend/plugin/parser/pg/query_span_omni.go`
+
+Until BYT-9082 (PL/pgSQL parser in omni) is complete, user-defined function calls need a bridge. When the lineage walker encounters a function call referencing a UDF, fall back to the existing ANTLR-based function analysis.
+
+**Step 1: Detect UDF calls in the expression walker**
+
+When `walkExpr` encounters a `FuncCallExpr`, check if it's a user-defined function by looking up the catalog's `UserProc` registry.
+
+**Step 2: For UDF table sources (RTEFunction)**
+
+Look up the function definition in metadata, then either:
+- For SQL language functions: parse the body with `pg.Parse()`, analyze with `AnalyzeSelectStmt()`, extract lineage
+- For PL/pgSQL functions: fall back to the existing `querySpanExtractor.findFunctionDefine()` logic
+
+**Step 3: Run function-related test cases**
+
+Expected: Function test cases pass (8 test cases).
+
+**Step 4: Commit**
+
+```bash
+git commit -m "feat(pg): bridge UDF analysis to ANTLR for omni QuerySpan"
+```
+
+---
+
+## Task 9: Handle the sourceColumns (accessed tables) collection
+
+**Files:**
+- Modify: `bytebase/backend/plugin/parser/pg/query_span_omni.go`
+
+The existing QuerySpan collects `SourceColumns` as a set of `ColumnResource` with empty `Column` field (table-level access). This is used for data masking to know which tables are accessed.
+
+**Step 1: Collect table-level access from RangeTable**
+
+Walk `Query.RangeTable` to collect all `RTERelation` entries. For each, emit a `ColumnResource{Database: db, Schema: schema, Table: table, Column: ""}`.
+
+**Step 2: Also collect from function body analysis**
+
+If function analysis produces additional source columns, merge them.
+
+**Step 3: Run tests checking sourcecolumns field**
+
+Expected: The `sourcecolumns` field in YAML matches.
+
+**Step 4: Commit**
+
+```bash
+git commit -m "feat(pg): collect accessed tables for omni QuerySpan sourceColumns"
+```
+
+---
+
+## Task 10: Handle edge cases and error recovery
+
+**Files:**
+- Modify: `bytebase/backend/plugin/parser/pg/query_span_omni.go`
+
+**Step 1: ResourceNotFoundError handling**
+
+When omni's `AnalyzeSelectStmt` fails because a table/column doesn't exist, catch the error and return a partial `QuerySpan` with `NotFoundError` set, matching current behavior.
+
+**Step 2: FunctionNotSupportedError handling**
+
+When a function can't be analyzed, return partial results with the error flag set.
+
+**Step 3: EXPLAIN statement handling**
+
+`EXPLAIN SELECT ...` should extract the inner SELECT. `EXPLAIN ANALYZE` returns just the access map without results. Check that `classifyQueryType` already handles this correctly.
+
+**Step 4: Run all 77 test cases**
+
+Run: `go test -v -count=1 -run ^TestGetQuerySpan$ github.com/bytebase/bytebase/backend/plugin/parser/pg`
+Expected: All 77 tests pass (46 query_span + 31 query_type).
+
+**Step 5: Commit**
+
+```bash
+git commit -m "feat(pg): handle edge cases and error recovery in omni QuerySpan"
+```
+
+---
+
+## Task 11: Clean up legacy ANTLR code
+
+**Files:**
+- Delete: `bytebase/backend/plugin/parser/pg/query_span_extractor.go` (3,868 lines)
+- Delete: `bytebase/backend/plugin/parser/pg/access_tables_antlr.go` (96 lines)
+- Modify: `bytebase/backend/plugin/parser/pg/query_span.go` (remove old extractor references)
+
+**Step 1: Remove old extractor file**
+
+Delete `query_span_extractor.go` entirely. If any helper functions are still needed by the UDF bridge (Task 8), extract them to a separate file first.
+
+**Step 2: Remove ANTLR access table extractor**
+
+Delete `access_tables_antlr.go` — replaced by `access_tables.go` which uses omni.
+
+**Step 3: Check for remaining ANTLR imports in the package**
+
+Run: `grep -r "antlr4-go/antlr" bytebase/backend/plugin/parser/pg/query_span*.go`
+Expected: No matches (all ANTLR usage removed from query span files).
+
+**Step 4: Run all tests one final time**
+
+Run: `go test -v -count=1 -run ^TestGetQuerySpan$ github.com/bytebase/bytebase/backend/plugin/parser/pg`
+Expected: All 77 tests pass.
+
+**Step 5: Run linter**
+
+Run: `golangci-lint run --allow-parallel-runners bytebase/backend/plugin/parser/pg/...`
+Expected: No issues.
+
+**Step 6: Build**
+
+Run: `go build -ldflags "-w -s" -p=16 -o ./bytebase-build/bytebase ./backend/bin/server/main.go`
+Expected: Builds successfully.
+
+**Step 7: Commit**
+
+```bash
+git add -A bytebase/backend/plugin/parser/pg/
+git commit -m "refactor(pg): remove legacy ANTLR QuerySpan extractor"
+```
+
+---
+
+## Task Summary
+
+| Task | Description | Lines changed (est.) | Risk |
+|------|-------------|---------------------|------|
+| 1 | Scaffold extractor + wire entry point | +80 | Low |
+| 2 | Catalog loading from metadata | +50 | Low |
+| 3 | Core getQuerySpan pipeline | +80 | Medium |
+| 4 | Column lineage walker | +200 | High — core logic |
+| 5 | Set operations | +40 | Medium |
+| 6 | View through-lineage | +20 | Low |
+| 7 | System functions | +20 (verify) | Low |
+| 8 | UDF bridge to ANTLR | +100 | High — complex bridging |
+| 9 | SourceColumns collection | +30 | Low |
+| 10 | Edge cases + error recovery | +50 | Medium |
+| 11 | Delete legacy code | -3,964 | Low — just deletion |
+
+**Net result:** ~670 lines added, ~3,964 lines deleted = **~3,300 lines removed**
+
+## Test Strategy
+
+All 77 existing YAML test cases serve as the acceptance criteria. The test runner (`query_span_test.go`) is untouched — it calls `GetQuerySpan()` which is the entry point we're re-wiring. Tests should pass identically after migration.
+
+Run the full test suite after each task. If a test fails, investigate before moving on — do not accumulate failures.
diff --git a/go.mod b/go.mod
index 76f17de481..143a39e63b 100644
--- a/go.mod
+++ b/go.mod
@@ -34,7 +34,7 @@ require (
github.com/bmatcuk/doublestar/v4 v4.10.0
github.com/bytebase/gomongo v0.0.0-20260324061529-f15b9a5add35
github.com/bytebase/lsp-protocol v0.0.0-20250324071136-1586d0c10ff0
- github.com/bytebase/omni v0.0.0-20260323084215-7bbe88e0d0ed
+ github.com/bytebase/omni v0.0.0-20260324084257-a8ae1438840a
github.com/caarlos0/env/v11 v11.4.0
github.com/cenkalti/backoff/v5 v5.0.3
github.com/cockroachdb/cockroachdb-parser v0.25.2
diff --git a/go.sum b/go.sum
index ee946f8e8b..56ef5dbd9a 100644
--- a/go.sum
+++ b/go.sum
@@ -253,8 +253,8 @@ github.com/bytebase/gomongo v0.0.0-20260324061529-f15b9a5add35 h1:SjcZSrUMNj6GZq
github.com/bytebase/gomongo v0.0.0-20260324061529-f15b9a5add35/go.mod h1:jHdAD+tN3bO2Hazme0crgkNiHqkDR/3Igesy1chhjLA=
github.com/bytebase/lsp-protocol v0.0.0-20250324071136-1586d0c10ff0 h1:bJ8NSf2K+pccl5m/wuu97fiYjDwpJH6IzURAq/3XA2U=
github.com/bytebase/lsp-protocol v0.0.0-20250324071136-1586d0c10ff0/go.mod h1:BEWMfiZtqshdmulKJcIsWb45MUaEvDO4CROcgi8dfFg=
-github.com/bytebase/omni v0.0.0-20260323084215-7bbe88e0d0ed h1:vJ//BI7+pFRujbQTKBVAcZtAwoLSrWKjMVXITo6P97c=
-github.com/bytebase/omni v0.0.0-20260323084215-7bbe88e0d0ed/go.mod h1:btZOCeNcueZehdqT+7YsLSVm+srVGSoPZYvFlITO2Z8=
+github.com/bytebase/omni v0.0.0-20260324084257-a8ae1438840a h1:DVUpZCKOHiNUu/0++lHmqMyrss42Ndinwzr1wipTBwA=
+github.com/bytebase/omni v0.0.0-20260324084257-a8ae1438840a/go.mod h1:btZOCeNcueZehdqT+7YsLSVm+srVGSoPZYvFlITO2Z8=
github.com/bytebase/parser v0.0.0-20260324035613-3b4d6e704551 h1:jmOIMyIEXoMWZ+TK91STbBMPRom7S/tWxosxYZDg9jk=
github.com/bytebase/parser v0.0.0-20260324035613-3b4d6e704551/go.mod h1:jeak/EfutSOAuWKvrFIT2IZunhWprM7oTFBRgZ9RCxo=
github.com/bytebase/pgx/v5 v5.0.0-20250212161523-96ff8aed8767 h1:YuR5G3LcxpO5ScSTA+Kdirxg9RW4TRc/v1t7N2Hfmbw=