gosqlx

Overview ¶

Package gosqlx provides high-level convenience functions for SQL parsing, validation, formatting, and metadata extraction, with automatic object pool management.

GoSQLX is a production-ready, high-performance SQL parsing SDK for Go that supports multiple SQL dialects with comprehensive SQL-99 and SQL:2003 feature support. The primary entry points are Parse, Validate, Format, and ParseWithDialect.

Overview ¶

This package wraps the lower-level tokenizer and parser APIs to provide a simple, ergonomic interface for common SQL operations. All object pool management is handled internally, making it ideal for applications that prioritize ease of use over fine-grained performance control.

Key functions:

• Parse: tokenizes and parses SQL, returning an *ast.AST
• Validate: checks whether SQL is syntactically valid without building a full AST
• Format: formats SQL text according to configurable style options
• ParseWithDialect: parses SQL using dialect-specific rules (PostgreSQL, MySQL, etc.)
• ParseMultiple: efficiently parses a batch of SQL statements by reusing pooled objects
• ParseWithContext: parse with context support for cancellation and timeouts

For performance-critical applications requiring fine-grained control over object lifecycle and pooling, use the lower-level APIs in pkg/sql/tokenizer and pkg/sql/parser directly.

Key Features ¶

• Blazing Fast: 1.38M+ ops/sec sustained, 1.5M+ peak throughput
• Memory Efficient: 60-80% reduction through intelligent object pooling
• Thread-Safe: Race-free, validated with comprehensive concurrent testing
• Zero-Copy: Direct byte slice operations with <1μs latency
• Multi-Dialect: PostgreSQL, MySQL, SQL Server, Oracle, SQLite support
• Production-Ready: ~80-85% SQL-99 compliance, battle-tested

Supported SQL Features (v1.6.0) ¶

SQL Standards Compliance:

• DML: SELECT, INSERT, UPDATE, DELETE with complex expressions
• DDL: CREATE TABLE/VIEW/INDEX, ALTER TABLE, DROP statements
• CTEs: WITH clause, RECURSIVE CTEs with proper termination
• Set Operations: UNION, EXCEPT, INTERSECT with proper precedence
• Window Functions: Complete SQL-99 support (ROW_NUMBER, RANK, DENSE_RANK, NTILE, LAG, LEAD, FIRST_VALUE, LAST_VALUE)
• Window Frames: ROWS/RANGE with BETWEEN clauses and frame bounds
• JOIN Types: INNER, LEFT, RIGHT, FULL OUTER, CROSS, NATURAL with USING/ON
• MERGE: SQL:2003 MERGE with WHEN MATCHED/NOT MATCHED clauses
• Grouping: GROUPING SETS, ROLLUP, CUBE (SQL-99 T431)
• FETCH: FETCH FIRST/NEXT with ROWS ONLY, WITH TIES, PERCENT (SQL-99 F861)
• Materialized Views: CREATE, DROP, REFRESH MATERIALIZED VIEW
• TRUNCATE: TRUNCATE TABLE with CASCADE/RESTRICT, RESTART/CONTINUE IDENTITY
• Expressions: BETWEEN, IN, LIKE, IS NULL, CASE, CAST, subqueries
• Ordering: NULLS FIRST/LAST in ORDER BY clauses (SQL-99 F851)

PostgreSQL Extensions (v1.6.0):

• LATERAL JOIN: Correlated subqueries in FROM clause
• JSON/JSONB Operators: ->, ->>, #>, #>>, @>, <@, ?, ?|, ?&, #-
• DISTINCT ON: PostgreSQL-specific row selection
• FILTER Clause: Conditional aggregation (SQL:2003 T612)
• RETURNING Clause: Return modified rows from INSERT/UPDATE/DELETE
• Aggregate ORDER BY: ORDER BY inside aggregate functions

Performance Characteristics ¶

Object Pooling:

• AST pool: sync.Pool-based AST container reuse
• Tokenizer pool: Reusable tokenizer instances
• Statement pools: Individual pools for SELECT, INSERT, UPDATE, DELETE
• Expression pools: Pooled identifiers, binary expressions, literals
• Pool efficiency: 95%+ hit rate in production workloads

Benchmarks (v1.6.0):

• Parse throughput: 1.38M+ operations/second sustained
• Peak throughput: 1.5M+ operations/second
• Tokenization: 8M+ tokens/second
• Latency: <1μs for complex queries with window functions
• Memory reduction: 60-80% with object pooling
• Token comparison: 14x faster with Type field (0.28ns vs 4.9ns)
• Keyword suggestions: 575x faster with caching

Thread Safety ¶

All functions in this package are thread-safe and race-free. The package has been validated through comprehensive concurrent testing with 20,000+ concurrent operations showing zero race conditions.

Object pools are safely managed with sync.Pool, providing lock-free performance while maintaining thread safety guarantees.

Error Handling ¶

All parsing errors are structured with error codes and detailed position information:

• E1xxx: Tokenization errors (unexpected character, invalid token)
• E2xxx: Parser errors (syntax error, unexpected token)
• E3xxx: Semantic errors (undefined reference, type mismatch)

Errors include:

• Precise line and column information
• Relevant SQL context excerpt
• Helpful error messages with suggestions
• Error recovery hints for common mistakes

Quick Start ¶

Basic SQL parsing:

sql := "SELECT * FROM users WHERE active = true"
ast, err := gosqlx.Parse(sql)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Parsed: %T\n", ast)

Common Usage Patterns ¶

Parsing with timeout:

ast, err := gosqlx.ParseWithTimeout(sql, 5*time.Second)
if err == context.DeadlineExceeded {
    log.Println("Parsing timed out")
}

Parsing multiple queries efficiently:

queries := []string{
    "SELECT * FROM users",
    "SELECT * FROM orders",
}
asts, err := gosqlx.ParseMultiple(queries)

Validating SQL syntax:

if err := gosqlx.Validate("SELECT * FROM users"); err != nil {
    fmt.Printf("Invalid SQL: %v\n", err)
}

Extracting metadata:

sql := "SELECT u.name, o.total FROM users u JOIN orders o ON u.id = o.user_id"
ast, _ := gosqlx.Parse(sql)
metadata := gosqlx.ExtractMetadata(ast)
fmt.Printf("Tables: %v, Columns: %v\n", metadata.Tables, metadata.Columns)

Memory Management ¶

The gosqlx package automatically manages object pools for optimal performance. When using the convenience functions (Parse, ParseMultiple, etc.), objects are automatically returned to pools after use.

For manual control over object lifecycle, use the lower-level APIs:

// Manual object pool management
tkz := tokenizer.GetTokenizer()
defer tokenizer.PutTokenizer(tkz)

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

// Use objects
tokens, err := tkz.Tokenize(sqlBytes)
result, err := parser.Parse(tokens)

IMPORTANT: Always use defer with pool return functions to prevent resource leaks and maintain optimal performance. Object pooling provides 60-80% memory reduction.

PostgreSQL JSON/JSONB Support ¶

Complete support for PostgreSQL JSON operators:

// Field access operators
SELECT data->'name' FROM users;           // Get JSON field as JSON
SELECT data->>'name' FROM users;          // Get JSON field as text

// Path access operators
SELECT data#>'{address,city}' FROM users; // Get nested value as JSON
SELECT data#>>'{address,city}' FROM users; // Get nested value as text

// Containment operators
SELECT * FROM users WHERE data @> '{"status":"active"}';  // Contains
SELECT * FROM users WHERE '{"status":"active"}' <@ data;  // Contained by

// Existence operators
SELECT * FROM users WHERE data ? 'email';          // Has key
SELECT * FROM users WHERE data ?| array['a','b']; // Has any key
SELECT * FROM users WHERE data ?& array['a','b']; // Has all keys

// Delete operator
SELECT data #- '{address,zip}' FROM users; // Delete at path

Window Functions ¶

Full SQL-99 window function support with all frame specifications:

// Ranking functions
SELECT name, salary,
    ROW_NUMBER() OVER (ORDER BY salary DESC) as row_num,
    RANK() OVER (PARTITION BY dept ORDER BY salary DESC) as rank,
    DENSE_RANK() OVER (ORDER BY score) as dense_rank,
    NTILE(4) OVER (ORDER BY score) as quartile
FROM employees;

// Analytic functions with offsets
SELECT date, amount,
    LAG(amount, 1) OVER (ORDER BY date) as prev_amount,
    LEAD(amount, 2, 0) OVER (ORDER BY date) as future_amount
FROM transactions;

// Window frames
SELECT date, amount,
    SUM(amount) OVER (
        ORDER BY date
        ROWS BETWEEN 2 PRECEDING AND CURRENT ROW
    ) as rolling_sum,
    AVG(amount) OVER (
        ORDER BY date
        RANGE UNBOUNDED PRECEDING
    ) as running_avg
FROM transactions;

Advanced SQL Features ¶

MERGE statements (SQL:2003):

MERGE INTO target t
USING source s ON t.id = s.id
WHEN MATCHED THEN
    UPDATE SET t.value = s.value
WHEN NOT MATCHED THEN
    INSERT (id, value) VALUES (s.id, s.value);

GROUPING SETS, ROLLUP, CUBE (SQL-99 T431):

-- Explicit grouping combinations
SELECT region, product, SUM(sales)
FROM orders
GROUP BY GROUPING SETS ((region), (product), (region, product), ());

-- Hierarchical subtotals
SELECT year, quarter, SUM(revenue)
FROM sales
GROUP BY ROLLUP (year, quarter);

-- All possible combinations
SELECT region, product, SUM(amount)
FROM sales
GROUP BY CUBE (region, product);

LATERAL JOIN (PostgreSQL):

SELECT u.name, recent_orders.order_date
FROM users u,
LATERAL (
    SELECT * FROM orders
    WHERE user_id = u.id
    ORDER BY order_date DESC
    LIMIT 3
) recent_orders;

FILTER clause (SQL:2003 T612):

SELECT
    COUNT(*) FILTER (WHERE status = 'active') AS active_count,
    SUM(amount) FILTER (WHERE type = 'credit') AS total_credits
FROM transactions;

RETURNING clause (PostgreSQL):

INSERT INTO users (name, email)
VALUES ('John', 'john@example.com')
RETURNING id, created_at;

UPDATE products
SET price = price * 1.1
WHERE category = 'Electronics'
RETURNING id, price;

Integration Examples ¶

Database query analysis:

func analyzeQuery(query string) error {
    ast, err := gosqlx.Parse(query)
    if err != nil {
        return fmt.Errorf("invalid SQL: %w", err)
    }

    // Extract metadata for query optimization
    tables := gosqlx.ExtractTables(ast)
    columns := gosqlx.ExtractColumns(ast)
    functions := gosqlx.ExtractFunctions(ast)

    fmt.Printf("Query uses %d tables, %d columns, %d functions\n",
        len(tables), len(columns), len(functions))
    return nil
}

SQL security scanning:

import "github.com/ajitpratap0/GoSQLX/pkg/sql/security"

func checkSQLSafety(query string) error {
    scanner := security.NewScanner()
    findings := scanner.Scan(query)

    for _, finding := range findings {
        if finding.Severity == security.SeverityCritical {
            return fmt.Errorf("SQL injection risk: %s", finding.Message)
        }
    }
    return nil
}

Query transformation:

func transformQuery(sql string) (string, error) {
    ast, err := gosqlx.Parse(sql)
    if err != nil {
        return "", err
    }

    // Use visitor pattern to transform AST
    // Then format back to SQL
    opts := gosqlx.DefaultFormatOptions()
    opts.UppercaseKeywords = true
    return gosqlx.Format(sql, opts)
}

Known Limitations ¶

While GoSQLX supports a comprehensive set of SQL features, the following are partially supported or not yet fully implemented:

1. CASE Expressions: Simple and searched CASE expressions in some contexts
2. CAST Expressions: Type conversion in complex expressions
3. IN Expressions: Complex value lists and nested subqueries in some contexts
4. BETWEEN Expressions: Range comparisons in complex expressions
5. Schema-Qualified Names: Some 3-part qualified names (db.schema.table)
6. Complex Recursive CTEs: Recursive CTEs with complex JOIN syntax

These limitations represent areas of ongoing development. For queries using these features, parsing may succeed with partial AST representation, or may fail with descriptive error messages.

CLI Tool Integration ¶

The gosqlx CLI tool provides command-line access to parsing functionality:

# Install CLI
go install github.com/ajitpratap0/GoSQLX/cmd/gosqlx@latest

# Validate SQL
gosqlx validate "SELECT * FROM users WHERE active = true"

# Format SQL
gosqlx format -i query.sql

# Analyze SQL structure
gosqlx analyze "SELECT COUNT(*) FROM orders GROUP BY status"

# Parse to JSON AST
gosqlx parse -f json query.sql

# Start LSP server for IDE integration
gosqlx lsp

LSP Server (v1.6.0) ¶

GoSQLX includes a full Language Server Protocol implementation for IDE integration:

# Start LSP server
gosqlx lsp

# With debug logging
gosqlx lsp --log /tmp/lsp.log

LSP Features:

• Real-time SQL syntax validation with diagnostics
• Hover documentation for 60+ SQL keywords and functions
• Intelligent autocomplete with 100+ keywords and 22 snippets
• SQL code formatting with customizable options
• Document symbols for SQL statement navigation
• Function signature help for 20+ SQL functions
• Quick fixes (add semicolon, uppercase keywords)

VSCode Extension:

• Search "GoSQLX" in VSCode marketplace
• Automatic integration with gosqlx binary
• Multi-dialect SQL support
• Customizable formatting preferences

Configuration ¶

GoSQLX can be configured via .gosqlx.yml file:

# .gosqlx.yml
dialect: postgresql
format:
  indent_size: 2
  uppercase_keywords: true
  max_line_length: 100
linter:
  rules:
    L001: error  # Trailing whitespace
    L007: warn   # Keyword case

See docs/CONFIGURATION.md for complete configuration reference.

Documentation ¶

Additional documentation:

• docs/GETTING_STARTED.md - Quick start guide for new users
• docs/USAGE_GUIDE.md - Comprehensive usage guide
• docs/LSP_GUIDE.md - LSP server and IDE integration
• docs/LINTING_RULES.md - All 10 linting rules (L001-L010)
• docs/CONFIGURATION.md - Configuration file reference
• docs/SQL_COMPATIBILITY.md - SQL dialect compatibility matrix

Production Deployment ¶

GoSQLX is production-ready and battle-tested:

• Race Detection: Zero race conditions (validated with 20,000+ concurrent operations)
• Performance: 1.5M ops/sec peak, 1.38M+ sustained throughput
• Unicode Support: Full international compliance (8 languages tested)
• SQL Compatibility: Multi-dialect with 115+ real-world queries validated
• Memory Management: Zero leaks detected, stable under extended load
• Error Handling: Robust recovery with precise position information

Quality Metrics:

• Thread Safety: 5/5 stars - Race-free codebase confirmed
• Performance: 5/5 stars - 1.38M+ ops/sec sustained, <1μs latency
• Reliability: 5/5 stars - 95%+ success rate on real-world SQL
• Memory Efficiency: 5/5 stars - 60-80% reduction with pooling

Package Structure ¶

The gosqlx package is part of the larger GoSQLX SDK:

pkg/
├── gosqlx/          # High-level convenience API (this package)
├── sql/
│   ├── tokenizer/   # Zero-copy SQL lexer
│   ├── parser/      # Recursive descent parser
│   ├── ast/         # Abstract Syntax Tree nodes
│   ├── keywords/    # SQL keyword definitions
│   └── security/    # SQL injection detection
├── models/          # Core data structures (100% test coverage)
├── errors/          # Structured error handling
├── metrics/         # Performance monitoring
├── linter/          # SQL linting engine (10 rules)
└── lsp/             # Language Server Protocol server

For fine-grained control, use the lower-level packages directly.

Contributing ¶

Contributions are welcome! See the project repository for contribution guidelines.

Repository: https://github.com/ajitpratap0/GoSQLX Issues: https://github.com/ajitpratap0/GoSQLX/issues Discussions: https://github.com/ajitpratap0/GoSQLX/discussions

License ¶

GoSQLX is licensed under the Apache License 2.0. See LICENSE file for details.

This file provides SQL metadata extraction functions for the gosqlx package.

The extraction functions traverse the Abstract Syntax Tree (AST) to collect metadata such as table names, column references, function calls, and qualified identifiers. These functions are useful for query analysis, security scanning, dependency tracking, and query optimization.

Extraction Functions Overview ¶

The gosqlx package provides six main extraction functions:

• ExtractTables: Simple table names (e.g., "users", "orders")
• ExtractTablesQualified: Qualified table names (e.g., "public.users")
• ExtractColumns: Simple column names (e.g., "name", "email")
• ExtractColumnsQualified: Qualified column names (e.g., "u.name")
• ExtractFunctions: Function names (e.g., "COUNT", "SUM")
• ExtractMetadata: All metadata in one call (convenience function)

All extraction functions are thread-safe and can be called concurrently on different AST instances. They return deduplicated results, so each identifier appears only once in the output regardless of how many times it appears in the query.

Performance Characteristics ¶

Extraction functions are optimized for performance:

• Single AST traversal per extraction call
• O(N) time complexity where N is the number of AST nodes
• HashMap-based deduplication for O(1) lookup
• Minimal memory allocation (reuses visitor pattern)

For large ASTs (1000+ nodes), expect extraction times <100μs on modern hardware.

Parser Limitations ¶

The extraction functions in this package are subject to the following parser limitations. These limitations represent SQL features that are partially supported or not yet fully implemented in the GoSQLX parser. As the parser evolves, these limitations may be addressed in future releases.

## Known Limitations

1. CASE Expressions: CASE expressions (simple and searched CASE) are not fully supported in the parser. Column references within CASE WHEN conditions and result expressions may not be extracted correctly.

   Example (not fully supported): SELECT CASE status WHEN 'active' THEN name ELSE 'N/A' END FROM users

2. CAST Expressions: CAST expressions for type conversion are not fully supported. Column references within CAST expressions may not be extracted.

   Example (not fully supported): SELECT CAST(price AS DECIMAL(10,2)) FROM products

3. IN Expressions: IN expressions with subqueries or complex value lists in WHERE clauses are not fully supported. Column references in IN lists may not be extracted correctly.

   Example (not fully supported): SELECT * FROM users WHERE status IN ('active', 'pending') SELECT * FROM orders WHERE user_id IN (SELECT id FROM users)

4. BETWEEN Expressions: BETWEEN expressions for range comparisons are not fully supported. Column references in BETWEEN bounds may not be extracted correctly.

   Example (not fully supported): SELECT * FROM products WHERE price BETWEEN min_price AND max_price

5. Complex Recursive CTEs: Recursive Common Table Expressions (CTEs) with complex JOIN syntax are not fully supported. Simple recursive CTEs work, but complex variations may fail to parse.

   Example (not fully supported): WITH RECURSIVE org_chart AS ( SELECT id, name, manager_id, 1 as level FROM employees WHERE manager_id IS NULL UNION ALL SELECT e.id, e.name, e.manager_id, o.level + 1 FROM employees e INNER JOIN org_chart o ON e.manager_id = o.id ) SELECT * FROM org_chart

## Workarounds

For queries using these unsupported features:

• Simplify complex expressions where possible
• Use alternative SQL syntax that is supported
• Extract metadata manually from the original SQL string
• Consider contributing parser enhancements to the GoSQLX project

## Reporting Issues

If you encounter parsing issues with SQL queries that should be supported, please report them at: https://github.com/ajitpratap0/GoSQLX/issues

package main

import (
	"fmt"
	"log"

	"github.com/ajitpratap0/GoSQLX/pkg/gosqlx"
)

func main() {
	// Window functions
	windowSQL := "SELECT name, ROW_NUMBER() OVER (PARTITION BY dept ORDER BY salary DESC) as rank FROM employees"
	ast1, err := gosqlx.Parse(windowSQL)
	if err != nil {
		log.Fatal(err)
	}

	// CTEs
	cteSQL := "WITH active AS (SELECT * FROM users WHERE active = true) SELECT * FROM active"
	ast2, err := gosqlx.Parse(cteSQL)
	if err != nil {
		log.Fatal(err)
	}

	// JOINs
	joinSQL := "SELECT u.name, o.total FROM users u INNER JOIN orders o ON u.id = o.user_id"
	ast3, err := gosqlx.Parse(joinSQL)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Parsed window: %d, CTE: %d, JOIN: %d\n", len(ast1.Statements), len(ast2.Statements), len(ast3.Statements))
}

Output:

Parsed window: 1, CTE: 1, JOIN: 1

package main

import (
	"fmt"
	"log"

	"github.com/ajitpratap0/GoSQLX/pkg/gosqlx"
)

func main() {
	sql := `SELECT
		u.username,
		COUNT(o.id) as total_orders,
		SUM(o.amount) as total_spent,
		UPPER(u.email) as email_upper
	FROM users u
	LEFT JOIN orders o ON u.id = o.user_id
	WHERE u.active = true AND o.status = 'completed'
	GROUP BY u.id, u.username, u.email
	HAVING COUNT(o.id) > 10
	ORDER BY total_spent DESC`

	ast, err := gosqlx.Parse(sql)
	if err != nil {
		log.Fatal(err)
	}

	metadata := gosqlx.ExtractMetadata(ast)

	fmt.Printf("Query Analysis:\n")
	fmt.Printf("- Joins %d tables\n", len(metadata.Tables))
	fmt.Printf("- References %d columns\n", len(metadata.Columns))
	fmt.Printf("- Uses %d functions\n", len(metadata.Functions))
}

Output:

Query Analysis:
- Joins 2 tables
- References 8 columns
- Uses 3 functions

package main

import (
	"fmt"
	"log"

	"github.com/ajitpratap0/GoSQLX/pkg/gosqlx"
)

func main() {
	queries := []string{
		"SELECT * FROM users",
		"SELECT * FROM orders",
		"SELECT * FROM products",
	}

	asts, err := gosqlx.ParseMultiple(queries)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Successfully parsed %d queries\n", len(asts))
}

Output:

Successfully parsed 3 queries

package main

import (
	"fmt"

	"github.com/ajitpratap0/GoSQLX/pkg/gosqlx"
)

func main() {
	queries := []string{
		"SELECT * FROM users",
		"INSERT INTO logs (message) VALUES ('test')",
		"UPDATE users SET active = false WHERE id = 1",
		"DELETE FROM temp_data WHERE created_at < NOW()",
	}

	if err := gosqlx.ValidateMultiple(queries); err != nil {
		fmt.Printf("Validation failed: %v\n", err)
		return
	}

	fmt.Printf("All %d queries are valid\n", len(queries))
}

Output:

All 4 queries are valid

package main

import (
	"fmt"
	"log"

	"github.com/ajitpratap0/GoSQLX/pkg/gosqlx"
)

func main() {
	sql := `
		SELECT
			u.id,
			u.name,
			COUNT(o.id) as order_count
		FROM users u
		LEFT JOIN orders o ON u.id = o.user_id
		WHERE u.active = true
		GROUP BY u.id, u.name
		ORDER BY order_count DESC
	`

	ast, err := gosqlx.Parse(sql)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Parsed complex query with %d statement(s)\n", len(ast.Statements))
}

Output:

Parsed complex query with 1 statement(s)

package main

import (
	"fmt"
	"log"

	"github.com/ajitpratap0/GoSQLX/pkg/gosqlx"
)

func main() {
	sql := `
		WITH active_users AS (
			SELECT * FROM users WHERE active = true
		)
		SELECT * FROM active_users
	`

	ast, err := gosqlx.Parse(sql)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Successfully parsed CTE query\n")
	_ = ast
}

Output:

Successfully parsed CTE query

package main

import (
	"fmt"

	"github.com/ajitpratap0/GoSQLX/pkg/gosqlx"
)

func main() {
	sql := "SELECT * FROM" // Invalid: missing table name

	ast, err := gosqlx.Parse(sql)
	if err != nil {
		fmt.Println("Parse error occurred")
		// In real code: log detailed error message
		_ = err
		return
	}

	_ = ast
}

Output:

Parse error occurred

package main

import (
	"fmt"
	"log"

	"github.com/ajitpratap0/GoSQLX/pkg/gosqlx"
)

func main() {
	sql := "SELECT u.name, u.email FROM users u WHERE u.active = true ORDER BY u.created_at"

	ast, err := gosqlx.Parse(sql)
	if err != nil {
		log.Fatal(err)
	}

	columns := gosqlx.ExtractColumns(ast)
	fmt.Printf("Found %d columns\n", len(columns))
}

Output:

Found 4 columns

package main

import (
	"fmt"
	"log"

	"github.com/ajitpratap0/GoSQLX/pkg/gosqlx"
)

func main() {
	sql := `WITH active_users AS (
		SELECT id, name FROM users WHERE active = true
	)
	SELECT name, COUNT(*) FROM active_users GROUP BY name`

	ast, err := gosqlx.Parse(sql)
	if err != nil {
		log.Fatal(err)
	}

	metadata := gosqlx.ExtractMetadata(ast)
	fmt.Printf("Tables found: %d\n", len(metadata.Tables))
}

Output:

Tables found: 2

package main

import (
	"fmt"
	"log"

	"github.com/ajitpratap0/GoSQLX/pkg/gosqlx"
)

func main() {
	sql := "SELECT COUNT(*), AVG(salary), UPPER(name) FROM employees"

	ast, err := gosqlx.Parse(sql)
	if err != nil {
		log.Fatal(err)
	}

	functions := gosqlx.ExtractFunctions(ast)
	fmt.Printf("Found %d functions\n", len(functions))
}

Output:

Found 3 functions

package main

import (
	"fmt"
	"log"

	"github.com/ajitpratap0/GoSQLX/pkg/gosqlx"
)

func main() {
	sql := `SELECT u.name, COUNT(o.id) as order_count
		FROM users u
		LEFT JOIN orders o ON u.id = o.user_id
		WHERE u.active = true
		GROUP BY u.name
		HAVING COUNT(o.id) > 5`

	ast, err := gosqlx.Parse(sql)
	if err != nil {
		log.Fatal(err)
	}

	metadata := gosqlx.ExtractMetadata(ast)
	fmt.Printf("Tables: %d, Columns: %d, Functions: %d\n",
		len(metadata.Tables), len(metadata.Columns), len(metadata.Functions))
}

Output:

Tables: 2, Columns: 4, Functions: 1

package main

import (
	"fmt"
	"log"

	"github.com/ajitpratap0/GoSQLX/pkg/gosqlx"
)

func main() {
	sql := "SELECT * FROM users u JOIN orders o ON u.id = o.user_id"

	ast, err := gosqlx.Parse(sql)
	if err != nil {
		log.Fatal(err)
	}

	tables := gosqlx.ExtractTables(ast)
	fmt.Printf("Found %d tables\n", len(tables))
}

Output:

Found 2 tables

package main

import (
	"fmt"
	"log"

	"github.com/ajitpratap0/GoSQLX/pkg/gosqlx"
)

func main() {
	sql := "SELECT * FROM users JOIN orders ON users.id = orders.user_id"

	ast, err := gosqlx.Parse(sql)
	if err != nil {
		log.Fatal(err)
	}

	tables := gosqlx.ExtractTablesQualified(ast)
	fmt.Printf("Found %d tables\n", len(tables))
}

Output:

Found 2 tables

package main

import (
	"fmt"
	"log"

	"github.com/ajitpratap0/GoSQLX/pkg/gosqlx"
)

func main() {
	sql := `SELECT
		name,
		salary,
		ROW_NUMBER() OVER (PARTITION BY department ORDER BY salary DESC) as rank,
		AVG(salary) OVER (PARTITION BY department) as dept_avg
	FROM employees`

	ast, err := gosqlx.Parse(sql)
	if err != nil {
		log.Fatal(err)
	}

	functions := gosqlx.ExtractFunctions(ast)
	fmt.Printf("Window functions found: %d\n", len(functions))
}

Output:

Window functions found: 2

package main

import (
	"fmt"
	"log"

	"github.com/ajitpratap0/GoSQLX/pkg/gosqlx"
)

func main() {
	sql := "SELECT * FROM users WHERE active = true"

	// Use default formatting options
	opts := gosqlx.DefaultFormatOptions()
	opts.AddSemicolon = true

	formatted, err := gosqlx.Format(sql, opts)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Formatted SQL length: %d\n", len(formatted))
}

Output:

Formatted SQL length: 40

package main

import (
	"fmt"
	"log"

	"github.com/ajitpratap0/GoSQLX/pkg/gosqlx"
)

func main() {
	sql := "SELECT id, name FROM users"

	opts := gosqlx.FormatOptions{
		IndentSize:        4,
		UppercaseKeywords: true,
		AddSemicolon:      true,
		SingleLineLimit:   80,
	}

	formatted, err := gosqlx.Format(sql, opts)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Formatted with custom options: %d chars\n", len(formatted))
}

Output:

Formatted with custom options: 27 chars

package main

import (
	"fmt"
	"log"

	"github.com/ajitpratap0/GoSQLX/pkg/gosqlx"
)

func main() {
	// Instead of manually managing tokenizer and parser:
	// tkz := tokenizer.GetTokenizer()
	// defer tokenizer.PutTokenizer(tkz)
	// tokens, err := tkz.Tokenize([]byte(sql))
	// ...
	// p := parser.NewParser()
	// defer p.Release()
	// ast, err := p.Parse(tokens)

	// Simply use:
	ast, err := gosqlx.Parse("SELECT * FROM users")
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Migrated to simple API: %d statement(s)\n", len(ast.Statements))
}

Output:

Migrated to simple API: 1 statement(s)

package main

import (
	"fmt"

	"github.com/ajitpratap0/GoSQLX/pkg/gosqlx"
)

func main() {
	// Use MustParse only with SQL literals you control
	// (e.g., in tests or initialization code)
	ast := gosqlx.MustParse("SELECT 1")

	fmt.Printf("Type: %T\n", ast)
}

Output:

Type: *ast.AST

package main

import (
	"fmt"
	"log"

	"github.com/ajitpratap0/GoSQLX/pkg/gosqlx"
)

func main() {
	// Useful when SQL is already in byte form (e.g., from file I/O)
	sqlBytes := []byte("SELECT * FROM users")

	ast, err := gosqlx.ParseBytes(sqlBytes)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Parsed from bytes: %d statement(s)\n", len(ast.Statements))
}

Output:

Parsed from bytes: 1 statement(s)

package main

import (
	"fmt"
	"log"

	"github.com/ajitpratap0/GoSQLX/pkg/gosqlx"
)

func main() {
	// Validate user input before executing
	userSQL := "SELECT * FROM users WHERE id = 1"

	// First validate
	if err := gosqlx.Validate(userSQL); err != nil {
		fmt.Println("Invalid SQL from user")
		return
	}

	// Parse to inspect structure
	ast, err := gosqlx.Parse(userSQL)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Valid query with %d statement(s)\n", len(ast.Statements))
}

Output:

Valid query with 1 statement(s)

package main

import (
	"fmt"
	"log"

	"github.com/ajitpratap0/GoSQLX/pkg/gosqlx"
)

func main() {
	sql := "SELECT * FROM users"

	ast, err := gosqlx.Parse(sql)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Parsed %d statement(s)\n", len(ast.Statements))
}

Output:

Parsed 1 statement(s)

package main

import (
	"fmt"

	"github.com/ajitpratap0/GoSQLX/pkg/gosqlx"
)

func main() {
	// Valid SQL
	if err := gosqlx.Validate("SELECT * FROM users"); err != nil {
		fmt.Println("Invalid SQL")
	} else {
		fmt.Println("Valid SQL")
	}

	// Invalid SQL
	if err := gosqlx.Validate("INVALID SQL"); err != nil {
		fmt.Println("Invalid SQL detected")
	}

}

Output:

Valid SQL
Invalid SQL detected

package main

import (
	"fmt"

	"github.com/ajitpratap0/GoSQLX/pkg/gosqlx"
)

func main() {
	queries := []string{
		"SELECT * FROM users",
		"INSERT INTO users (name) VALUES ('test')",
		"UPDATE users SET active = true WHERE id = 1",
	}

	if err := gosqlx.ValidateMultiple(queries); err != nil {
		fmt.Printf("Validation failed: %v\n", err)
		return
	}

	fmt.Println("All queries are valid")
}

Output:

All queries are valid

package main

import (
	"fmt"
	"log"

	"github.com/ajitpratap0/GoSQLX/pkg/gosqlx"
)

func main() {
	userSQL := "SELECT u.id, u.name FROM users u WHERE u.status = 'active'"

	// First validate
	if err := gosqlx.Validate(userSQL); err != nil {
		fmt.Println("Invalid SQL")
		return
	}

	// Parse and extract metadata
	ast, err := gosqlx.Parse(userSQL)
	if err != nil {
		log.Fatal(err)
	}

	metadata := gosqlx.ExtractMetadata(ast)

	// Check if accessing sensitive tables
	sensitiveTable := "users"
	for _, table := range metadata.Tables {
		if table == sensitiveTable {
			fmt.Printf("Query accesses sensitive table: %s\n", sensitiveTable)
		}
	}
}

Output:

Query accesses sensitive table: users

package main

import (
	"fmt"
	"log"

	"github.com/ajitpratap0/GoSQLX/pkg/gosqlx"
)

func main() {
	sql := "SELECT name, salary, ROW_NUMBER() OVER (ORDER BY salary DESC) as rank FROM employees"

	ast, err := gosqlx.Parse(sql)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Successfully parsed window function query\n")
	_ = ast
}

Output:

Successfully parsed window function query