GoSQLX

What is GoSQLX?

GoSQLX is a production-ready SQL parsing SDK for Go. It tokenizes, parses, and generates ASTs from SQL with zero-copy optimizations and intelligent object pooling - parsing a simple SELECT in about 349 ns (~2.9M parses/sec).

Why GoSQLX?

• Not an ORM - a parser. You get the AST, you decide what to do with it.
• Not slow - zero-copy tokenization, sync.Pool recycling, no allocations on hot paths.
• Not limited - PostgreSQL, MySQL, MariaDB, SQL Server, Oracle, SQLite, Snowflake, ClickHouse. CTEs, window functions, MERGE, set operations.
• Not just a library - CLI, VS Code extension, GitHub Action, MCP server, WASM playground, Python bindings.

Install

Go library

go get github.com/ajitpratap0/GoSQLX

CLI

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

VS Code

code --install-extension ajitpratap0.gosqlx

The extension bundles the binary, so there is no extra setup. Learn more.

MCP server

claude mcp add --transport http gosqlx https://mcp.gosqlx.dev/mcp

7 SQL tools in Claude, Cursor, or any MCP client. MCP guide.

Claude Code plugin (skills, slash commands, SQL reviewer agent): /plugin marketplace add ajitpratap0/GoSQLX then /plugin install gosqlx@gosqlx - details.

ChatGPT app: add https://mcp.gosqlx.dev/mcp as a connector in developer mode for an interactive analysis widget - details.

GitHub Action

- uses: ajitpratap0/GoSQLX@v1
  with:
    files: '**/*.sql'
    validate: true

Quick start

Source: examples/readme_quickstart/main.go, compiled in CI against HEAD and the latest release.

package main

import (
	"context"
	"errors"
	"fmt"
	"log"

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

func main() {
	ctx := context.Background()

	// ParseTree is the recommended entry point. It returns an
	// opaque handle with built-in helpers.
	tree, err := gosqlx.ParseTree(ctx, "SELECT id, name FROM users WHERE active = true",
		gosqlx.WithDialect("postgresql"))
	if err != nil {
		// Sentinel errors work with errors.Is
		if errors.Is(err, gosqlx.ErrSyntax) {
			log.Fatalf("syntax error: %v", err)
		}
		log.Fatal(err)
	}
	fmt.Println("Tables:", tree.Tables())
	fmt.Println(tree.Format(gosqlx.WithIndent(2), gosqlx.WithUppercaseKeywords(true)))

	// Walk the AST - typed walkers avoid the type-assertion dance:
	tree.WalkSelects(func(s *ast.SelectStatement) bool {
		fmt.Printf("  SELECT with %d columns\n", len(s.Columns))
		return true
	})

	// The legacy Parse/Format/Validate API still works for v1.x code.
	// See docs/MIGRATION.md for the Tree migration guide.
}

Output:

Tables: [users]
SELECT id, name
FROM users
WHERE active = true
  SELECT with 2 columns

Formatting turns one-line SQL into a readable query:

Features

• Parser - zero-copy tokenizer, recursive descent parser and full AST generation.
• Analysis - SQL injection scanner, 30 lint rules (L001-L030), 20 optimizer rules and metadata extraction.
• Tooling - AST-based formatter, query transforms API, VS Code extension and GitHub Action.
• Syntax highlighting - dialect-aware highlighting for terminals (ANSI), HTML/CSS, JSON spans, LSP semantic tokens and WASM; gosqlx highlight query.sql or gosqlx.HighlightANSI(sql).
• Multi-dialect - 8 dialects with dedicated grammar support: PostgreSQL, MySQL, MariaDB, SQL Server, Oracle, SQLite, Snowflake, ClickHouse. The --dialect flag and WithDialect accept 11 names: those 8 (postgresql, mysql, mariadb, sqlserver, oracle, sqlite, snowflake, clickhouse) plus generic, bigquery and redshift. BigQuery and Redshift have no dialect-specific keyword set (they use the generic keywords) and only capability-gated grammar, such as BigQuery's QUALIFY, PIVOT/UNPIVOT, UNNEST in FROM and (struct).field access.
• AI-ready - MCP server with 7 tools, public remote endpoint, Streamable HTTP.
• Tested - race-detector clean in CI, ~80-85% SQL-99 (estimated).

Documentation

• Getting Started - parse your first SQL in 5 minutes
• Usage Guide - comprehensive patterns and examples
• API Reference - complete API documentation
• CLI Guide - command-line tool reference
• SQL Compatibility - dialect support matrix
• MCP Guide - AI assistant integration
• Architecture - system design deep-dive
• Benchmarks - performance data and methodology
• Changelog - what changed in each version

Contributing

GoSQLX is built by contributors like you. Whether it's a bug fix, new feature, documentation improvement, or just a typo - every contribution matters.

git clone https://github.com/ajitpratap0/GoSQLX.git && cd GoSQLX
task check    # fmt → vet → lint → test (with race detection)

1. Fork & branch from main
2. Write tests - we use TDD and require race-free code
3. Run task check - must pass before PR
4. Open a PR - we review within 24 hours

Contributing Guide · Code of Conduct · Governance

Community

Questions or ideas: Discussions. Found a bug or want a feature: Issues.

License

Apache License 2.0 - see LICENSE for details.

---