GoSQLX Architecture Documentation#

┌────────────────────────────────────────────────────────────────────────────────┐
│                          Application Layer & Tools                             │
│  ┌─────────────┬──────────────┬──────────────┬─────────────┬───────────────┐  │
│  │ CLI Tool    │ LSP Server   │  Linter      │  Security   │  MCP Server   │  │
│  │ (validate,  │ (JSON-RPC    │  (30 rules:  │  Scanner    │  (7 tools,    │  │
│  │  format,    │  handler,    │   L001-L030, │  (injection │   HTTP,       │  │
│  │  analyze,   │  rate limit, │   style,     │   detection)│   bearer auth,│  │
│  │  parse)     │  doc mgmt)   │   safety)    │             │   streaming)  │  │
│  └─────────────┴──────────────┴──────────────┴─────────────┴───────────────┘  │
└────────────────────────────────────────────────────────────────────────────────┘
                                ▼
┌───────────────────────────────────────────────────────────────────┐
│                    GoSQLX API (pkg/gosqlx)                        │
│  High-level API providing SQL parsing, validation, formatting     │
└───────────────────────────────────────────────────────────────────┘
                                ▼
┌──────────────┬────────────────────────┬──────────────────────────┐
│  Tokenizer   │      Parser            │         AST              │
│  (zero-copy, │  (recursive descent,   │  (14 statement types,    │
│   120+ token │   14 statement types,  │   pooled nodes,          │
│   types,     │   PostgreSQL features, │   visitor pattern)       │
│   dialect    │   window functions)    │                          │
│   support)   │                        │                          │
├──────────────┼────────────────────────┼──────────────────────────┤
│  Object Pool │    Token Stream        │    Node Factory          │
│  (tokenizer, │  (position tracking,   │  (statement/expression   │
│   parser,    │   conversion layer)    │   pooling)               │
│   AST pools) │                        │                          │
└──────────────┴────────────────────────┴──────────────────────────┘
                                ▼
┌───────────────────────────────────────────────────────────────────┐
│       Core Models, Error Handling, Metrics & Keywords             │
│  ┌──────────┬──────────┬──────────┬──────────┬─────────────────┐ │
│  │ Models   │ Errors   │ Metrics  │ Keywords │ Configuration   │ │
│  │ (Token,  │ (codes,  │ (atomic  │ (5 SQL   │ (YAML-based,    │ │
│  │  Span,   │  pos.    │  counters│  dialects│  linter, format │ │
│  │  Loc.)   │  track)  │  lock-   │  120+    │  security opts) │ │
│  │  100%    │  91.9%   │  free)   │  kwds)   │  81.8% coverage │ │
│  │  coverage│  coverage│  73.9%   │  100%    │                 │ │
│  └──────────┴──────────┴──────────┴──────────┴─────────────────┘ │
└───────────────────────────────────────────────────────────────────┘

// TokenType represents the type of a SQL token
type TokenType int

// Range-based categorization for O(1) type checking
const (
    // Token ranges (non-overlapping for fast dispatch)
    TokenRangeBasicStart      TokenType = 10   // Basic tokens
    TokenRangeBasicEnd        TokenType = 30
    TokenRangeStringStart     TokenType = 30   // String literals
    TokenRangeStringEnd       TokenType = 50
    TokenRangeOperatorStart   TokenType = 50   // Operators
    TokenRangeOperatorEnd     TokenType = 150
    TokenRangeKeywordStart    TokenType = 200  // SQL keywords
    TokenRangeKeywordEnd      TokenType = 500
    TokenRangeDataTypeStart   TokenType = 430  // Data types
    TokenRangeDataTypeEnd     TokenType = 450
)

// Fast token type classification (14x faster than string comparisons)
func (t TokenType) IsKeyword() bool {
    return t >= TokenRangeKeywordStart && t < TokenRangeKeywordEnd
}

func (t TokenType) IsOperator() bool {
    return t >= TokenRangeOperatorStart && t < TokenRangeOperatorEnd
}

func (t TokenType) IsLiteral() bool {
    return (t >= TokenRangeStringStart && t < TokenRangeStringEnd) ||
           t == TokenTypeNumber
}

func (t TokenType) IsDMLKeyword() bool {
    return t == TokenTypeSelect || t == TokenTypeInsert ||
           t == TokenTypeUpdate || t == TokenTypeDelete
}

func (t TokenType) IsDDLKeyword() bool {
    return t == TokenTypeCreate || t == TokenTypeAlter || t == TokenTypeDrop
}

func (t TokenType) IsJoinKeyword() bool {
    return t >= TokenTypeJoin && t <= TokenTypeUsing
}

func (t TokenType) IsWindowKeyword() bool {
    return t >= TokenTypeOver && t <= TokenTypeExclude
}

func (t TokenType) IsAggregateFunction() bool {
    return t >= TokenTypeCount && t <= TokenTypeMax
}

func (t TokenType) IsDataType() bool {
    return t >= TokenRangeDataTypeStart && t < TokenRangeDataTypeEnd
}

func (t TokenType) IsConstraint() bool {
    return t >= TokenTypePrimary && t <= TokenTypeNullable
}

func (t TokenType) IsSetOperation() bool {
    return t == TokenTypeUnion || t == TokenTypeExcept || t == TokenTypeIntersect
}

// JSON/JSONB operators
TokenTypeArrow         // -> (field access, returns JSON)
TokenTypeLongArrow     // ->> (field access, returns text)
TokenTypeHashArrow     // #> (path access, returns JSON)
TokenTypeHashLongArrow // #>> (path access, returns text)
TokenTypeAtArrow       // @> (contains)
TokenTypeArrowAt       // <@ (contained by)
TokenTypeHashMinus     // #- (delete at path)
TokenTypeQuestionPipe  // ?| (key exists any)
TokenTypeQuestionAnd   // ?& (key exists all)

// Keywords
TokenTypeLateral       // LATERAL (correlated subquery in FROM)
TokenTypeFilter        // FILTER (conditional aggregation)
TokenTypeDistinct      // DISTINCT (with ON support)

┌──────────────────────────────────────┐
│           Tokenizer                   │
├──────────────────────────────────────┤
│  ┌──────────────────────────────┐    │
│  │    Input Buffer ([]byte)      │    │
│  └──────────┬───────────────────┘    │
│             ▼                         │
│  ┌──────────────────────────────┐    │
│  │    Scanner State Machine      │    │
│  └──────────┬───────────────────┘    │
│             ▼                         │
│  ┌──────────────────────────────┐    │
│  │    Token Recognition          │    │
│  │  - Keywords                   │    │
│  │  - Identifiers                │    │
│  │  - Literals                   │    │
│  │  - Operators                  │    │
│  └──────────┬───────────────────┘    │
│             ▼                         │
│  ┌──────────────────────────────┐    │
│  │    Position Tracking          │    │
│  │  - Line/Column                │    │
│  │  - Byte Offset                │    │
│  └──────────┬───────────────────┘    │
│             ▼                         │
│  ┌──────────────────────────────┐    │
│  │    Token Stream Output        │    │
│  └──────────────────────────────┘    │
└──────────────────────────────────────┘

┌──────────────────────────────────────┐
│            Parser                     │
├──────────────────────────────────────┤
│  ┌──────────────────────────────┐    │
│  │    Token Stream Input         │    │
│  └──────────┬───────────────────┘    │
│             ▼                         │
│  ┌──────────────────────────────┐    │
│  │    Recursive Descent Parser   │    │
│  │  - Statement Parser           │    │
│  │  - Expression Parser          │    │
│  │  - Clause Parser              │    │
│  └──────────┬───────────────────┘    │
│             ▼                         │
│  ┌──────────────────────────────┐    │
│  │    AST Node Construction      │    │
│  │  - Node Factory               │    │
│  │  - Type Validation            │    │
│  └──────────┬───────────────────┘    │
│             ▼                         │
│  ┌──────────────────────────────┐    │
│  │    AST Output                 │    │
│  └──────────────────────────────┘    │
└──────────────────────────────────────┘

pkg/sql/parser/
├── parser.go          # Core parser, entry points, and utilities
├── select.go          # SELECT statement parsing
├── dml.go             # INSERT, UPDATE, DELETE, MERGE parsing
├── cte.go             # Common Table Expressions (WITH clause)
├── expressions.go     # Expression parsing (BETWEEN, IN, LIKE, etc.)
├── window.go          # Window functions (OVER, PARTITION BY)
├── grouping.go        # GROUPING SETS, ROLLUP, CUBE
├── alter.go           # ALTER TABLE statements
├── ddl.go             # DDL statements (CREATE, DROP, REFRESH, TRUNCATE)
└── token_conversion.go # Internal token conversion (unexported)

parseStatement()  # Fast ModelType (int) dispatch with O(1) switching
├── parseWithStatement()              # WITH (CTEs)
├── parseSelectWithSetOperations()    # SELECT + UNION/EXCEPT/INTERSECT
├── parseInsertStatement()            # INSERT (with RETURNING)
├── parseUpdateStatement()            # UPDATE (with RETURNING)
├── parseDeleteStatement()            # DELETE (with RETURNING)
├── parseMergeStatement()             # MERGE
├── parseCreateStatement()            # CREATE (TABLE, VIEW, MATERIALIZED VIEW, INDEX)
├── parseAlterTableStmt()             # ALTER TABLE
├── parseDropStatement()              # DROP
├── parseRefreshStatement()           # REFRESH MATERIALIZED VIEW
└── parseTruncateStatement()          # TRUNCATE

parseSelectExpression()
├── parseDistinctOnClause()           # DISTINCT ON (col1, col2, ...)
└── parseLateralTableReference()      # LATERAL (subquery)

parseFunctionCall()
└── parseAggregateOrderBy()           # ORDER BY inside aggregates
    ├── STRING_AGG(expr, delim ORDER BY col)
    ├── ARRAY_AGG(expr ORDER BY col)
    └── JSON_AGG(expr ORDER BY col)

parseExpression()
├── parseJSONOperator()               # ->, ->>, #>, #>>, @>, <@, #-, ?, ?|, ?&
└── parseFilterClause()               # FILTER (WHERE condition)

parseReturningClause()                # RETURNING * | col1, col2 | expr AS alias

// DML Statements
SelectStatement             // SELECT with JOINs, window functions, CTEs
InsertStatement            // INSERT with multiple value sets
UpdateStatement            // UPDATE with WHERE clause
DeleteStatement            // DELETE with WHERE clause
MergeStatement             // MERGE with MATCHED/NOT MATCHED clauses
TruncateStatement          // TRUNCATE TABLE

// DDL Statements
CreateTableStatement       // CREATE TABLE with columns, constraints
CreateViewStatement        // CREATE VIEW
CreateMaterializedViewStatement  // CREATE MATERIALIZED VIEW
CreateIndexStatement       // CREATE INDEX
AlterTableStatement        // ALTER TABLE (add/drop columns, constraints)
AlterStatement             // Generic ALTER (roles, policies, etc.)
DropStatement              // DROP (tables, views, indexes)
RefreshMaterializedViewStatement // REFRESH MATERIALIZED VIEW

// Query Composition
WithClause                 // WITH (CTEs) - can contain any statement
SetOperation               // UNION/EXCEPT/INTERSECT

// Basic Expressions
Identifier                 // Table/column names
Literal                    // String, number, boolean literals
BinaryExpression          // a + b, a = b, etc.
UnaryExpression           // NOT, -x, etc.

// Complex Expressions
FunctionCall              // func(args) with optional OVER clause
WindowSpec                // Window function specification
BetweenExpression         // x BETWEEN a AND b
InExpression              // x IN (values) or x IN (subquery)
LikeExpression            // x LIKE pattern
IsNullExpression          // x IS NULL / IS NOT NULL
CaseExpression            // CASE WHEN ... THEN ... END

// Grouping
GroupingSet               // Individual grouping set
RollupGrouping            // ROLLUP(columns)
CubeGrouping              // CUBE(columns)

SQL Text ([]byte)
         │
         ▼
┌─────────────────────┐
│   Tokenizer         │ ← tokenizer.GetTokenizer()
├─────────────────────┤
│ Lexical Analysis    │
│ - Zero-copy ops     │
│ - Position tracking │
└──────────┬──────────┘
           │ []models.TokenWithSpan (with Location)
           ▼
┌─────────────────────┐
│  Token Converter    │
├─────────────────────┤
│ Models → AST tokens │
│ Position mapping    │
└──────────┬──────────┘
           │ []token.Token + positions
           ▼
┌─────────────────────┐
│      Parser         │ ← parser.GetParser()
├─────────────────────┤
│ Recursive Descent   │
│ AST Construction    │
└──────────┬──────────┘
           │ *ast.AST
           ▼
┌─────────────────────┐
│  Application Use    │
│ - Validation        │
│ - Transformation    │
│ - Code Generation   │
└──────────┬──────────┘
           │
           ▼
    Return to Pools
    (PutTokenizer, PutParser, ReleaseAST)

// 1. Input SQL
sql := "SELECT * FROM users"

// 2. Tokenization (pkg/sql/tokenizer)
tkz := tokenizer.GetTokenizer()
defer tokenizer.PutTokenizer(tkz)

tokens, err := tkz.Tokenize([]byte(sql))
// Returns: []models.TokenWithSpan with position info
// [{Token: SELECT, Start: {Line:1, Col:1}, End: {Line:1, Col:6}}, ...]

// 3. Token conversion (pkg/sql/parser/token_conversion.go)
p := parser.NewParser()
defer p.Release()
// Returns: []token.Token for parser consumption

// 4. Parsing (pkg/sql/parser)
p := parser.GetParser()
defer parser.PutParser(p)

ast, err := p.ParseFromModelTokens(tokens)
// Returns: *ast.AST containing statements

// 5. Access parsed structure
selectStmt := ast.Statements[0].(*ast.SelectStatement)
// selectStmt.Columns contains parsed column expressions
// selectStmt.From contains table references

// CORRECT - Always use defer for cleanup
tkz := tokenizer.GetTokenizer()
defer tokenizer.PutTokenizer(tkz)  // MANDATORY

p := parser.GetParser()
defer parser.PutParser(p)           // MANDATORY

astObj := ast.NewAST()
defer ast.ReleaseAST(astObj)        // MANDATORY

// Use the objects...

// Tokens reference original input bytes
type Token struct {
    Type  TokenType
    Value string // Points to original input
}

// No copying during tokenization
func (t *Tokenizer) readIdentifier() Token {
    start := t.pos
    // Scan without copying
    for isIdentifierChar(t.peek()) {
        t.advance()
    }
    // Reference original bytes
    return Token{
        Type:  TokenTypeIdentifier,
        Value: string(t.input[start:t.pos]), // Single allocation
    }
}

type Tokenizer struct {
    // Reusable buffers
    buffer []byte
    tokens []TokenWithSpan
}

func (t *Tokenizer) Reset() {
    // Clear without deallocating
    t.buffer = t.buffer[:0]
    t.tokens = t.tokens[:0]
    t.pos = 0
}

func ProcessLargeQuery(sql string) {
    estimatedTokens := len(sql) / 5 // Heuristic
    
    tokens := make([]Token, 0, estimatedTokens)
    // Avoids reallocation during append
}

// Process multiple queries concurrently
func ProcessConcurrent(queries []string) []Result {
    results := make([]Result, len(queries))
    var wg sync.WaitGroup

    for i, sql := range queries {
        wg.Add(1)
        go func(idx int, query string) {
            defer wg.Done()

            // Each goroutine gets its own instances from pool
            tkz := tokenizer.GetTokenizer()
            defer tokenizer.PutTokenizer(tkz)

            p := parser.GetParser()
            defer parser.PutParser(p)

            tokens, _ := tkz.Tokenize([]byte(query))
            p := parser.NewParser()
            defer p.Release()
            ast, _ := p.ParseFromModelTokens(tokens)

            results[idx] = Result{AST: ast}
        }(i, sql)
    }

    wg.Wait()
    return results
}

// Available metrics
type Metrics struct {
    QueriesParsed     int64  // Total queries processed
    TokensGenerated   int64  // Total tokens created
    BytesProcessed    int64  // Total SQL bytes scanned
    Errors            int64  // Parsing errors encountered
    PoolHits          int64  // Pool reuse count
    PoolMisses        int64  // Pool allocations
}

// Usage
snapshot := metrics.GetSnapshot()
fmt.Printf("Queries: %d, Pool hit rate: %.2f%%\n",
    snapshot.QueriesParsed,
    float64(snapshot.PoolHits) / float64(snapshot.PoolHits + snapshot.PoolMisses) * 100)

// Scan for security issues
issues := security.ScanQuery(sqlBytes)
for _, issue := range issues {
    fmt.Printf("Security: %s - %s (severity: %s)\n",
        issue.Type, issue.Description, issue.Severity)
}

// Monitor query execution
monitor := monitor.New()
monitor.RecordQuery(sql, duration, err)

stats := monitor.GetStats()
fmt.Printf("Avg duration: %v, Error rate: %.2f%%\n",
    stats.AvgDuration, stats.ErrorRate*100)

┌─────────────────────────────────────────────────────────────┐
│                     LSP Server (pkg/lsp)                     │
├─────────────────────────────────────────────────────────────┤
│  ┌────────────┐      ┌────────────┐      ┌──────────────┐  │
│  │  Server    │─────▶│  Handler   │─────▶│  Documents   │  │
│  │ (server.go)│      │(handler.go)│      │(documents.go)│  │
│  └────────────┘      └────────────┘      └──────────────┘  │
│        │                    │                     │          │
│        │                    │                     │          │
│   JSON-RPC 2.0        Request/Notify        Document        │
│   over stdio          Dispatcher            Manager         │
│        │                    │                     │          │
│        ▼                    ▼                     ▼          │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              Protocol Types (protocol.go)             │  │
│  │  - Request/Response                                   │  │
│  │  - Diagnostics (errors with positions)                │  │
│  │  - Completion (keywords, functions, snippets)         │  │
│  │  - Hover (documentation)                              │  │
│  │  - Formatting (indent, keyword case)                  │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│              Core SQL Components (Tokenizer/Parser)          │
└─────────────────────────────────────────────────────────────┘

type Server struct {
    reader    *bufio.Reader      // stdio reader
    writer    io.Writer           // stdio writer with mutex
    writeMu   sync.Mutex          // Thread-safe write
    documents *DocumentManager    // Open document tracking
    handler   *Handler            // Request dispatcher
    logger    *log.Logger         // Optional debug logging

    // Rate limiting (atomic counters)
    requestCount int64
    lastReset    time.Time
    rateMu       sync.Mutex
}

type Document struct {
    URI        string      // file:// URI
    LanguageID string      // "sql" language identifier
    Version    int         // Document version (increments on change)
    Content    string      // Full SQL content
    Lines      []string    // Cached line splits for position lookup
}

type DocumentManager struct {
    mu        sync.RWMutex              // Thread-safe access
    documents map[string]*Document      // URI → Document mapping
}

// Start LSP server via CLI
$ gosqlx lsp
$ gosqlx lsp --log /tmp/lsp.log  // With debug logging

// VSCode integration (.vscode/settings.json)
{
  "gosqlx.lsp.enabled": true,
  "gosqlx.format.indent": 2,
  "gosqlx.format.uppercaseKeywords": true
}

┌─────────────────────────────────────────────────────────────┐
│                    Linter (pkg/linter)                       │
├─────────────────────────────────────────────────────────────┤
│  ┌────────────┐      ┌────────────┐      ┌──────────────┐  │
│  │   Linter   │─────▶│   Rules    │─────▶│   Context    │  │
│  │(linter.go) │      │ (rule.go)  │      │(context.go)  │  │
│  └────────────┘      └────────────┘      └──────────────┘  │
│        │                    │                     │          │
│        │                    │                     │          │
│   File/Dir/String      Rule Interface       SQL + Tokens    │
│   Linting Engine       (Check/Fix)          + AST Context   │
│        │                    │                     │          │
│        ▼                    ▼                     ▼          │
│  ┌──────────────────────────────────────────────────────┐  │
│  │                30 Built-in Rules                      │  │
│  │  Whitespace (6): L001-L005, L010                      │  │
│  │  Style (3): L006, L008, L009                          │  │
│  │  Keywords (1): L007 (case consistency)                │  │
│  │  Safety (5): L011-L015                                │  │
│  │  Performance (8): L016-L023                           │  │
│  │  Naming (7): L024-L030                                │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│       Tokenizer → Parser → AST (best-effort parsing)        │
└─────────────────────────────────────────────────────────────┘

type Linter struct {
    rules []Rule  // Configured linting rules
}

// Create linter with specific rules
linter := linter.New(
    whitespace.NewTrailingWhitespace(),
    keywords.NewKeywordCase(true), // uppercase
    style.NewCommaPlacement("trailing"),
)

// Lint operations
fileResult := linter.LintFile("query.sql")
dirResult := linter.LintDirectory("./sql", "*.sql")
stringResult := linter.LintString(sqlContent, "inline.sql")

type Result struct {
    Files           []FileResult  // Per-file results
    TotalFiles      int           // File count
    TotalViolations int           // Total violations across all files
}

type FileResult struct {
    Filename   string       // File path
    Violations []Violation  // All violations found
    Error      error        // Fatal error (if any)
}

type Rule interface {
    ID() string                                    // L001, L002, etc.
    Name() string                                  // Human-readable name
    Description() string                           // What the rule checks
    Severity() Severity                            // error/warning/info
    Check(ctx *Context) ([]Violation, error)      // Find violations
    CanAutoFix() bool                              // Supports auto-fix?
    Fix(content string, v []Violation) (string, error)  // Apply fixes
}

type Violation struct {
    Rule       string          // Rule ID (e.g., "L001")
    RuleName   string          // Human-readable rule name
    Severity   Severity        // error/warning/info
    Message    string          // Violation description
    Location   models.Location // Line/column position
    Line       string          // Actual line content
    Suggestion string          // How to fix
    CanAutoFix bool            // Auto-fix available?
}

type BaseRule struct {
    id, name, description string
    severity              Severity
    canAutoFix            bool
}

// Embed BaseRule to avoid boilerplate
type TrailingWhitespace struct {
    BaseRule
}

type Context struct {
    SQL      string                    // Raw SQL content
    Filename string                    // Source filename
    Lines    []string                  // Line-by-line split
    Tokens   []models.TokenWithSpan    // Tokenizer output (optional)
    AST      *ast.AST                  // Parsed AST (optional)
    ParseErr error                     // Parser error (if any)
}

// Context builders
ctx := NewContext(sql, filename)
ctx.WithTokens(tokens)           // Add token stream
ctx.WithAST(astObj, parseErr)    // Add AST (best-effort)

# CLI usage (runs the style rules L001-L010)
$ gosqlx lint query.sql
$ gosqlx lint --auto-fix query.sql      # Apply available auto-fixes
$ gosqlx lint --max-length 120 *.sql    # Set the L005 line length

// Library usage: all 30 rules
result, err := gosqlx.Lint("DELETE FROM users")
// result.Violations contains L011 (Delete Without WHERE)

┌─────────────────────────────────────────────────────────────┐
│               Security Scanner (pkg/sql/security)            │
├─────────────────────────────────────────────────────────────┤
│  ┌────────────────────────────────────────────────────────┐ │
│  │                Scanner (scanner.go)                     │ │
│  ├────────────────────────────────────────────────────────┤ │
│  │  Pattern Detection (8 types):                          │ │
│  │  1. Tautologies (1=1, 'a'='a')                         │ │
│  │  2. Comment Bypasses (--, /**/, #)                     │ │
│  │  3. UNION-based (UNION SELECT, information_schema)     │ │
│  │  4. Stacked Queries (; DROP, ; DELETE)                 │ │
│  │  5. Time-based (SLEEP, WAITFOR, pg_sleep)              │ │
│  │  6. Out-of-band (xp_cmdshell, LOAD_FILE)               │ │
│  │  7. Dangerous Functions (EXEC, sp_executesql)          │ │
│  │  8. Boolean-based (conditional logic exploitation)     │ │
│  └────────────────────────────────────────────────────────┘ │
│                              │                               │
│                              ▼                               │
│  ┌────────────────────────────────────────────────────────┐ │
│  │          Detection Methods (dual-layer):                │ │
│  │  - Regex Pattern Matching (pre-compiled, sync.Once)    │ │
│  │  - AST Analysis (structure-aware detection)            │ │
│  └────────────────────────────────────────────────────────┘ │
│                              │                               │
│                              ▼                               │
│  ┌────────────────────────────────────────────────────────┐ │
│  │          Severity Classification:                       │ │
│  │  CRITICAL: Definite injection (OR 1=1 --)              │ │
│  │  HIGH: Likely injection (suspicious patterns)          │ │
│  │  MEDIUM: Potentially unsafe (needs review)             │ │
│  │  LOW: Informational findings                           │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      AST (for structure analysis)            │
└─────────────────────────────────────────────────────────────┘

type Scanner struct {
    minSeverity Severity  // Filter findings by severity
}

// Create scanner
scanner := security.NewScanner()
scanner.SetMinSeverity(security.SeverityHigh)  // Filter to HIGH+

// Scan AST
results := scanner.Scan(astObj)
for _, finding := range results.Findings {
    fmt.Printf("[%s] %s at line %d: %s\n",
        finding.Severity, finding.Pattern, finding.Line, finding.Description)
}

type ScanResult struct {
    Findings        []Finding  // All detected issues
    CriticalCount   int        // Count by severity
    HighCount       int
    MediumCount     int
    LowCount        int
    ScannedAt       time.Time  // Scan timestamp
}

type Finding struct {
    Pattern     PatternType    // Injection pattern type
    Severity    Severity       // CRITICAL/HIGH/MEDIUM/LOW
    Description string         // Human-readable description
    Line        int            // Source line number
    Column      int            // Source column number
    Evidence    string         // Matched SQL fragment
    Suggestion  string         // How to fix
}

// Package-level pattern compilation (sync.Once)
var (
    compiledPatterns     map[PatternType][]*regexp.Regexp
    compiledPatternsOnce sync.Once
)

func initCompiledPatterns() {
    compiledPatternsOnce.Do(func() {
        compiledPatterns = make(map[PatternType][]*regexp.Regexp)
        // Time-based patterns
        compiledPatterns[PatternTimeBased] = []*regexp.Regexp{
            regexp.MustCompile(`(?i)\bSLEEP\s*\(`),
            regexp.MustCompile(`(?i)\bWAITFOR\s+DELAY\b`),
            // ... more patterns
        }
        // ... other pattern types
    })
}

# CLI usage
$ gosqlx analyze query.sql
$ gosqlx analyze --security-only query.sql
$ gosqlx analyze --min-severity HIGH query.sql

# Programmatic usage
scanner := security.NewScanner()
scanner.SetMinSeverity(security.SeverityHigh)
results := scanner.Scan(ast)

for _, finding := range results.Findings {
    log.Printf("[%s] %s: %s", finding.Severity, finding.Pattern, finding.Description)
}

$ gosqlx analyze suspicious.sql

Security Findings:
  [CRITICAL] Tautology at line 3: Always-true condition '1=1'
  [HIGH] Comment Bypass at line 5: Trailing comment may indicate injection

Suggestions:
  - Use parameterized queries instead of string concatenation
  - Validate and sanitize all user inputs
  - Implement prepared statements

cmd/gosqlx-mcp/main.go
  └─ LoadConfig() + New() + Start()
       └─ pkg/mcp.Server
            ├─ BearerAuthMiddleware (optional, wraps next http.Handler)
            └─ StreamableHTTPServer (mark3labs/mcp-go)
                 └─ 7 registered tool handlers
                      ├─ validate_sql    → pkg/gosqlx.Validate / ParseWithDialect
                      ├─ format_sql      → pkg/gosqlx.Format
                      ├─ parse_sql       → pkg/gosqlx.Parse
                      ├─ extract_metadata→ pkg/gosqlx.Parse + ExtractMetadata
                      ├─ security_scan   → pkg/sql/security.NewScanner().ScanSQL
                      ├─ lint_sql        → pkg/linter.New(L001-L010).LintString
                      └─ analyze_sql     → concurrent fan-out of all 6 above