# GoSQLX API Reference

Source: https://gosqlx.dev/docs/reference/api/

GoSQLX is split into small packages with a one-way dependency chain. Most programs only need the high-level `gosqlx` package; the lower-level packages are there when you need control over pooling, tokens or individual AST nodes.

Each package has its own reference page. Signatures on [pkg.go.dev](https://pkg.go.dev/github.com/ajitpratap0/GoSQLX) are generated from the source and are authoritative when the two disagree.

New to GoSQLX? Start with [Getting Started](/docs/getting-started/), then pick a task guide such as [Parse PostgreSQL in Go](/docs/guides/parse-postgresql-in-go/) or [Extract table names from SQL in Go](/docs/guides/extract-table-names-from-sql-in-go/).

## Packages

| Package | Import path | Use it for |
|---|---|---|
| [gosqlx](/docs/reference/api/gosqlx/) | `pkg/gosqlx` | Parsing, validation, formatting, linting and metadata extraction with pooling handled for you |
| [tokenizer](/docs/reference/api/tokenizer/) | `pkg/sql/tokenizer` | Zero-copy lexing of SQL bytes into tokens |
| [parser](/docs/reference/api/parser/) | `pkg/sql/parser` | Building an AST from tokens |
| [ast](/docs/reference/api/ast/) | `pkg/sql/ast` | Statement and expression node types, pools and visitors |
| [keywords](/docs/reference/api/keywords/) | `pkg/sql/keywords` | Keyword tables and dialect identifiers |
| [models](/docs/reference/api/models/) | `pkg/models` | Tokens, spans and source locations |
| [errors](/docs/reference/api/errors/) | `pkg/errors` | Structured errors with codes, positions and hints |
| [metrics](/docs/reference/api/metrics/) | `pkg/metrics` | Production counters and timings |
| [security](/docs/reference/api/security/) | `pkg/sql/security` | SQL injection pattern detection |
| [highlight](/docs/reference/api/highlight/) | `pkg/highlight` | Dialect-aware SQL syntax highlighting as spans, ANSI, HTML and CSS |
| [linter](/docs/reference/api/linter/) | `pkg/linter` | The lint engine and its rules |
| [lsp](/docs/reference/api/lsp/) | `pkg/lsp` | The Language Server Protocol server |
| [mcp](/docs/reference/api/mcp/) | `pkg/mcp` | The Model Context Protocol server |
| [config](/docs/reference/api/config/) | `pkg/config` | Configuration loading for the CLI, LSP and library |

All import paths are relative to `github.com/ajitpratap0/GoSQLX/`.

## High-Level API

Moved to the [gosqlx package reference](/docs/reference/api/gosqlx/).

## Tokenizer API

Moved to the [tokenizer package reference](/docs/reference/api/tokenizer/).

## Parser API

Moved to the [parser package reference](/docs/reference/api/parser/).

## AST API

Moved to the [ast package reference](/docs/reference/api/ast/).

## Keywords Package

Moved to the [keywords package reference](/docs/reference/api/keywords/).

## Models

Moved to the [models package reference](/docs/reference/api/models/).

## Error Handling

Moved to the [errors package reference](/docs/reference/api/errors/). Every error code is listed in [Error Codes](/docs/reference/error-codes/).

## Metrics Package

Moved to the [metrics package reference](/docs/reference/api/metrics/).

## Security Package

Moved to the [security package reference](/docs/reference/api/security/).

## Highlight Package

Moved to the [highlight package reference](/docs/reference/api/highlight/). The guide with examples is [Syntax Highlighting](/docs/guides/syntax-highlighting/).

## Linter Package

Moved to the [linter package reference](/docs/reference/api/linter/). Every rule is listed in [Linting Rules](/docs/reference/linting-rules/).

## LSP Package

Moved to the [lsp package reference](/docs/reference/api/lsp/).

## MCP Package

Moved to the [mcp package reference](/docs/reference/api/mcp/).

## Configuration Package

Moved to the [config package reference](/docs/reference/api/config/).

## Performance Considerations

### Object Pooling

**Always use `defer` with pool return functions:**

```go
// Tokenizer
tkz := tokenizer.GetTokenizer()
defer tokenizer.PutTokenizer(tkz)

// Parser
p := parser.NewParser()
defer p.Release()

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

// Statements
stmt := ast.NewSelectStatement()
defer ast.ReleaseSelectStatement(stmt)
```

### Batch Processing

Use batch functions for multiple queries:

```go
// Reuses pooled objects across the batch
asts, err := gosqlx.ParseMultiple(queries)

// More efficient validation
err := gosqlx.ValidateMultiple(queries)
```

### Context and Timeouts

Use context for long-running operations:

```go
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

astNode, err := gosqlx.ParseWithContext(ctx, complexSQL)
```

For measured throughput and latency, see the [benchmarks page](https://gosqlx.dev/benchmarks/), which labels every number with its stage, hardware and Go version.

## Complete Example

```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "github.com/ajitpratap0/GoSQLX/pkg/gosqlx"
    "github.com/ajitpratap0/GoSQLX/pkg/sql/ast"
    "github.com/ajitpratap0/GoSQLX/pkg/sql/security"
    "github.com/ajitpratap0/GoSQLX/pkg/metrics"
    "github.com/ajitpratap0/GoSQLX/pkg/config"
)

func main() {
    // Load configuration
    cfg, _ := config.Load(".gosqlx.yml")

    // Enable metrics
    metrics.Enable()
    defer func() {
        snapshot := metrics.GetSnapshot()
        fmt.Printf("Processed %d queries with %.2f%% success rate\n",
            snapshot.TotalQueries, snapshot.SuccessRate)
    }()

    sql := `
        -- PostgreSQL features demonstration
        WITH RECURSIVE active_users AS (
            SELECT id, name, manager_id, 1 as level
            FROM employees
            WHERE active = true AND manager_id IS NULL

            UNION ALL

            SELECT e.id, e.name, e.manager_id, au.level + 1
            FROM employees e
            INNER JOIN active_users au ON e.manager_id = au.id
            WHERE au.level < 10
        )
        SELECT DISTINCT ON (dept_id)
               u.id,
               u.name,
               COUNT(o.id) FILTER (WHERE o.status = 'completed') as completed_orders,
               STRING_AGG(o.product, ', ' ORDER BY o.date DESC NULLS LAST) as recent_products,
               ROW_NUMBER() OVER (PARTITION BY u.dept_id ORDER BY COUNT(o.id) DESC) as dept_rank,
               u.metadata->>'email' as email,
               u.metadata->'address'->>'city' as city
        FROM active_users u
        LEFT JOIN LATERAL (
            SELECT * FROM orders
            WHERE user_id = u.id
            ORDER BY order_date DESC
            LIMIT 5
        ) o ON true
        WHERE u.created_at >= '2024-01-01'
        GROUP BY u.id, u.name, u.dept_id, u.metadata
        HAVING COUNT(o.id) > 5
        ORDER BY dept_id, completed_orders DESC NULLS LAST
        FETCH FIRST 10 ROWS WITH TIES
        RETURNING u.id, u.name, completed_orders
    `

    // Parse SQL with timeout
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()

    astNode, err := gosqlx.ParseWithContext(ctx, sql)
    if err != nil {
        log.Fatal("Parse error:", err)
    }
    defer ast.ReleaseAST(astNode)

    // Security scan
    scanner := security.NewScanner()
    secResults := scanner.Scan(astNode)
    if secResults.HasCritical() {
        fmt.Println("CRITICAL SECURITY ISSUES FOUND:")
        for _, f := range secResults.Findings {
            if f.Severity == security.SeverityCritical {
                fmt.Printf("  - [%s] %s: %s\n", f.Severity, f.Pattern, f.Description)
            }
        }
    } else {
        fmt.Println("Security scan: CLEAN")
    }

    // Lint SQL
    lintResult, err := gosqlx.Lint(sql)
    if err != nil {
        log.Fatal(err)
    }

    if len(lintResult.Violations) > 0 {
        fmt.Printf("\nLinting violations: %d\n", len(lintResult.Violations))
        for _, v := range lintResult.Violations {
            fmt.Printf("  [%s] %s at line %d\n", v.Rule, v.Message, v.Location.Line)
        }
    } else {
        fmt.Println("Linting: PASSED")
    }

    // Analyze AST structure
    if len(astNode.Statements) > 0 {
        if stmt, ok := astNode.Statements[0].(*ast.SelectStatement); ok {
            fmt.Printf("\nQuery Analysis:\n")
            fmt.Printf("  Columns: %d\n", len(stmt.Columns))
            fmt.Printf("  DISTINCT ON: %v\n", len(stmt.DistinctOn) > 0)

            if stmt.With != nil {
                fmt.Printf("  CTEs: %d (Recursive: %v)\n",
                    len(stmt.With.CTEs), stmt.With.Recursive)
            }

            if len(stmt.Windows) > 0 {
                fmt.Printf("  Window Functions: %d\n", len(stmt.Windows))
            }

            // Check for PostgreSQL features
            hasLateral := false
            for _, from := range stmt.From {
                if from.Lateral {
                    hasLateral = true
                    break
                }
            }
            fmt.Printf("  LATERAL JOIN: %v\n", hasLateral)

            // Check for FILTER clause
            hasFilter := false
            for _, col := range stmt.Columns {
                if fc, ok := col.(*ast.FunctionCall); ok && fc.Filter != nil {
                    hasFilter = true
                    break
                }
            }
            fmt.Printf("  FILTER Clause: %v\n", hasFilter)

            if stmt.FetchClause != nil {
                fmt.Printf("  FETCH FIRST: %v rows (WITH TIES: %v)\n",
                    *stmt.FetchClause.Count, stmt.FetchClause.WithTies)
            }

            if len(stmt.Returning) > 0 {
                fmt.Printf("  RETURNING: %d columns\n", len(stmt.Returning))
            }
        }
    }

    fmt.Println("\nSQL parsed, validated, and analyzed successfully!")
}
```

**Output:**
```
Security scan: CLEAN

Linting violations: 2
  [L003] Multiple consecutive blank lines at line 11
  [L005] Line length exceeds 120 characters at line 17

Query Analysis:
  Columns: 7
  DISTINCT ON: true
  CTEs: 1 (Recursive: true)
  Window Functions: 1
  LATERAL JOIN: true
  FILTER Clause: true
  FETCH FIRST: 10 rows (WITH TIES: true)
  RETURNING: 3 columns

SQL parsed, validated, and analyzed successfully!
Processed 1 queries with 100.00% success rate
```

## Additional Resources

- [Getting Started](/docs/getting-started/): install and parse your first query
- [Usage Guide](/docs/usage-guide/): patterns for services and batch jobs
- [SQL Compatibility](/docs/reference/sql-compatibility/): dialect and feature coverage
- [Error Codes](/docs/reference/error-codes/): every error code with causes and fixes
- [Linting Rules](/docs/reference/linting-rules/): all built-in lint rules
- [Configuration](/docs/reference/configuration/): the `.gosqlx.yml` file
- [Benchmarks](https://gosqlx.dev/benchmarks/): measured performance with stage, hardware and Go version
- [Examples](https://github.com/ajitpratap0/GoSQLX/tree/main/examples): runnable programs