Database governance built for humans and agents — controlling changes and access across every major database.
Go cicddata-governancedata-maskingdata-securitydatabase-accessdatabase-governancedevopsdevsecopsflywaygitopsliquibasemongodbmysqloraclepostgresqlschema-migrationssecuritysql-clientsqlservertidb
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.goindex 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 implementationquerySpan, 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.gonew file mode 100644index 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.mdnew file mode 100644index 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.modindex 76f17de481..143a39e63b 100644--- a/go.mod+++ b/go.mod@@ -34,7 +34,7 @@ require (github.com/bmatcuk/doublestar/v4 v4.10.0github.com/bytebase/gomongo v0.0.0-20260324061529-f15b9a5add35github.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-a8ae1438840agithub.com/caarlos0/env/v11 v11.4.0github.com/cenkalti/backoff/v5 v5.0.3github.com/cockroachdb/cockroachdb-parser v0.25.2diff --git a/go.sum b/go.sumindex ee946f8e8b..56ef5dbd9a 100644--- a/go.sum+++ b/go.sum@@ -253,8 +253,8 @@ github.com/bytebase/gomongo v0.0.0-20260324061529-f15b9a5add35 h1:SjcZSrUMNj6GZqgithub.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=