Getting Started#

Welcome! This guide will get you parsing SQL in under 5 minutes. No prior experience with GoSQLX required.

Step 1: Install GoSQLX (30 seconds)#

Requirements: Go 1.26+

Option A: Install CLI Tool (Recommended)#

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

Option B: Library Only#

go get github.com/ajitpratap0/GoSQLX

Verify installation:

# Check Go version
go version  # Should show Go 1.26+

# If you installed CLI:
gosqlx --version

Step 2: Validate Your First Query (1 minute)#

The fastest way to get started is with the CLI:

# Validate SQL syntax (from stdin)
echo "SELECT * FROM users WHERE active = true" | gosqlx validate
# Output: ✅ Valid SQL

# Or validate SQL files
gosqlx validate query.sql

# Format SQL with intelligent indentation (from stdin)
echo "select * from users where age>18" | gosqlx format
# Output:
# SELECT *
# FROM users
# WHERE age > 18

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

Available CLI Commands:

• validate - Ultra-fast SQL validation with security scanning
• format - High-performance SQL formatting with style options
• analyze - Advanced SQL analysis with complexity metrics
• parse - AST structure inspection (JSON/text output)
• lint - Check SQL code for style issues (rules L001-L010; all 30 rules run through the Go library with gosqlx.Lint)
• transpile - Convert SQL between dialects (MySQL ↔ PostgreSQL, PostgreSQL → SQLite)
• optimize - Run optimization advisor (OPT-001 through OPT-020)
• action - GitHub Actions integration with annotations
• stats - Object pool utilization metrics
• watch - Watch mode for continuous validation
• lsp - Start Language Server Protocol server for IDE integration
• config - Manage configuration files (.gosqlx.yml)
• completion - Shell autocompletion for bash/zsh/fish

More CLI examples:

# Security scanning for SQL injection
gosqlx validate --security query.sql

# Lint SQL files with auto-fix
gosqlx lint --auto-fix queries/*.sql

# Start LSP server for VSCode/Neovim
gosqlx lsp --log /tmp/lsp.log

# Format with configuration
gosqlx format --config .gosqlx.yml query.sql

See CLI Guide for complete documentation.

Step 3: Parse Your First Query in Go (2 minutes)#

Use GoSQLX in your Go application with the simple API:

Create main.go:#

package main

import (
    "fmt"
    "log"

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

func main() {
    // Parse SQL in one line - that's it!
    ast, err := gosqlx.Parse("SELECT * FROM users WHERE active = true")
    if err != nil {
        log.Fatal(err)
    }

    // Success!
    fmt.Printf("✓ Successfully parsed SQL!\n")
    fmt.Printf("  Type: %T\n", ast)
    fmt.Printf("  Statements: %d\n", len(ast.Statements))
}

Run it:

go mod init myproject
go get github.com/ajitpratap0/GoSQLX
go run main.go

Expected output:

✓ Successfully parsed SQL!
  Type: *ast.AST
  Statements: 1

That's it! Just 3 lines of code. No pool management, no manual cleanup - everything is handled automatically.

For a tour of the features (PostgreSQL extensions, security scanning, linting), see the Feature Tour.

Step 4: Common Use Cases (1 minute)#

Validate SQL in Your Application#

func ValidateUserQuery(sql string) error {
    // Simple validation
    if err := gosqlx.Validate(sql); err != nil {
        return err
    }

    // With security scanning
    scanner := security.NewScanner()
    result := scanner.Scan(sql)
    if len(result.Threats) > 0 {
        return fmt.Errorf("security threats detected: %v", result.Threats)
    }

    return nil
}

Process Multiple Queries#

func ProcessBatch(queries []string) error {
    asts, err := gosqlx.ParseMultiple(queries)
    if err != nil {
        return err
    }

    for i, ast := range asts {
        fmt.Printf("Query %d: %d statement(s)\n", i+1, len(ast.Statements))
    }
    return nil
}

Lint SQL Before Deployment#

func ValidateCodeStyle(sql string) error {
    result, err := gosqlx.Lint(sql)
    if err != nil {
        return err
    }

    if len(result.Violations) > 0 {
        return fmt.Errorf("found %d style violations", len(result.Violations))
    }

    return nil
}

Use in CI/CD#

# In your .github/workflows/test.yml
- name: Validate SQL
  run: |
    # Validate syntax
    gosqlx validate migrations/*.sql

    # Check security
    gosqlx validate --security queries/*.sql

    # Enforce style
    gosqlx lint --fail-on-warn migrations/*.sql queries/*.sql

    # Format check
    gosqlx format --check --diff queries/*.sql

IDE Integration with LSP#

# Start LSP server for VSCode/Neovim
gosqlx lsp --log /tmp/lsp.log

# Or in VSCode settings.json
{
  "sql.lsp.command": "gosqlx",
  "sql.lsp.args": ["lsp"]
}

What's Next?#

Essential Guides:#

• Feature Tour - PostgreSQL extensions, security scanning, and linting examples
• Usage Guide - Comprehensive patterns and examples
• CLI Guide - Full CLI documentation and all commands
• LSP Guide - Complete LSP server documentation for IDE integration
• MCP Server Guide - Use GoSQLX as MCP tools inside Claude, Cursor, and other AI assistants
• Linting Rules - All 30 linting rules reference
• Configuration - Configuration file (.gosqlx.yml) guide
• API Reference - Complete API documentation
• Examples - Real-world code examples

Feature Guides:#

• Dialect-Aware Transforms:

  • transform.FormatSQLWithDialect(stmt, dialect) for dialect-specific SQL output
  • transform.ParseSQLWithDialect(sql, dialect) for dialect-aware parsing
  • TOP (SQL Server) / FETCH FIRST (Oracle) / LIMIT (PostgreSQL, MySQL, SQLite, Snowflake, ClickHouse)

• SQL Transpilation:

  • MySQL ↔ PostgreSQL (AUTO_INCREMENT ↔ SERIAL, TINYINT(1) ↔ BOOLEAN)
  • PostgreSQL → SQLite (SERIAL → INTEGER, arrays → TEXT)
  • gosqlx transpile --from <dialect> --to <dialect> CLI subcommand

• Live Schema Introspection:

  • gosqlx.LoadSchema(ctx, loader) for dialect-agnostic metadata querying
  • PostgreSQL, MySQL, and SQLite loaders in pkg/schema/db
  • Tables, columns, indexes, foreign keys

• Expanded Dialects:

  • Snowflake at 100% QA pass (87/87: MATCH_RECOGNIZE, @stage, SAMPLE, QUALIFY, VARIANT, time-travel)
  • ClickHouse 83% QA pass at v1.14.0, up from 53% (nested types, parametric aggregates, WITH FILL, CODEC); now 83/83 as of v1.15.0
  • MariaDB with SEQUENCE, temporal tables, CONNECT BY

• IDE Integration:

  • LSP server with real-time diagnostics
  • Semantic tokens + diagnostic debouncing
  • Code completion for SQL keywords
  • Auto-formatting on save
  • See LSP Guide for setup instructions

• Security Features:

  • SQL injection pattern detection
  • Severity classification (HIGH/MEDIUM/LOW)
  • OpenSSF Scorecard workflow
  • See Usage Guide for security scanning patterns

• Code Quality:

  • 30 built-in linter rules (safety, performance, naming, style)
  • Auto-fix capabilities for common issues
  • OPT-001 through OPT-020 optimization advisor
  • Query fingerprinting + normalization
  • See Linting Rules for complete reference

Advanced Topics:#

• Low-Level API - For performance-critical applications (>100K queries/sec)
• Object Pooling - Manual resource management for fine-grained control
• Multi-Dialect Support - PostgreSQL, MySQL, MariaDB, SQL Server, Oracle, SQLite, Snowflake, ClickHouse
• Unicode Support - Full international character support
• SQL Compatibility - See SQL Compatibility for dialect matrix

See Usage Guide for advanced patterns.

Troubleshooting#

"command not found: gosqlx"#

Solution: Make sure $GOPATH/bin is in your PATH:

export PATH="$PATH:$(go env GOPATH)/bin"

"cannot find package"#

Solution: Run go mod tidy to download dependencies:

go mod init myproject
go get github.com/ajitpratap0/GoSQLX
go mod tidy

"tokenization failed: unexpected character"#

Solution: Check for invalid SQL syntax. Use CLI to debug:

gosqlx validate "your SQL here"

Need Help?#

• Troubleshooting Guide - Common issues and solutions
• GitHub Issues - Report bugs or ask questions
• Discussions - Community Q&A

Feature Highlights#

Production-Ready Performance#

• ~0.6 µs to parse a window-function query (parse stage only, Apple M4, Go 1.27; see performance_baselines.json)
• Zero race conditions - validated with comprehensive concurrent testing

SQL Compliance#

• ~80-85% SQL-99 compliance including window functions, CTEs, set operations
• Snowflake at 100% of the QA corpus (87/87); ClickHouse at 100% (83/83 as of v1.15.0)
• Multi-dialect support - PostgreSQL, MySQL, MariaDB, SQL Server, Oracle, SQLite, Snowflake, ClickHouse
• Full Unicode support for international SQL processing

Enterprise Features#

• Thread-safe - Race-free codebase confirmed through extensive testing
• Memory efficient - 60-80% memory reduction with object pooling
• Security scanning - Built-in SQL injection detection
• IDE integration - LSP server for VSCode, Neovim, and other editors
• Code quality - 30 linter rules for consistent SQL style
• Dialect-aware transforms - Round-trip SQL with dialect-specific syntax
• Live schema introspection - Query Postgres/MySQL/SQLite metadata at runtime
• SQL transpilation - Convert between MySQL, PostgreSQL, and SQLite

What You've Learned#

• ✓ Installing GoSQLX (library and CLI)
• ✓ Validating and formatting SQL with CLI
• ✓ Parsing SQL in Go applications with simple API
• ✓ Using advanced features (dialect-aware transforms, transpilation, schema introspection, 30 linter rules)
• ✓ Common use cases and patterns
• ✓ Where to find more help

Time to first success: < 5 minutes

Questions? Open an issue or start a discussion on GitHub!

Built by the GoSQLX community