GoSQLX

什么是 GoSQLX？

GoSQLX 是一款适用于生产环境的 Go SQL 解析 SDK。它会对 SQL 进行分词、解析并生成 AST，采用零拷贝优化和智能对象池——解析简单的 SELECT 语句仅需约 349 ns（约 2.9M 次解析/秒）。

为什么选择 GoSQLX？

• 不是 ORM，而是解析器。你可以获取 AST，并自行决定如何处理。
• 速度不慢：零拷贝分词、使用 sync.Pool 回收复用，热点路径上不进行内存分配。
• 功能不受限：支持 PostgreSQL、MySQL、MariaDB、SQL Server、Oracle、SQLite、Snowflake、ClickHouse，以及 CTE、窗口函数、MERGE 和集合运算。
• 不只是一个库：还提供 CLI、VS Code 扩展、GitHub Action、MCP 服务、WASM 在线体验环境和 Python 绑定。

安装

Go 库

go get github.com/ajitpratap0/GoSQLX

CLI

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

VS Code

code --install-extension ajitpratap0.gosqlx

该扩展已捆绑二进制文件，无需额外设置。了解详情。

MCP 服务

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

在 Claude、Cursor 或任何 MCP 客户端中使用 7 种 SQL 工具。MCP 指南。

Claude Code 插件（技能、斜杠命令、SQL 审查 Agent）：先运行 /plugin marketplace add ajitpratap0/GoSQLX，再运行 /plugin install gosqlx@gosqlx - 详情。

ChatGPT 应用：在开发者模式下，将 https://mcp.gosqlx.dev/mcp 添加为连接器，即可使用交互式分析小组件 - 详情。

GitHub Action

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

## 快速开始

来源：examples/readme_quickstart/main.go，在 CI 中针对 HEAD 和最新版本进行编译。

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.
}

输出：

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

格式化会将单行 SQL 转换为易读的查询：

功能

• 解析器 - 零拷贝分词器、递归下降解析器和完整的 AST 生成。
• 分析 - SQL 注入扫描器、30 条代码检查规则（L001-L030）、20 条优化器规则和元数据提取。
• 工具 - 基于 AST 的格式化器、查询转换 API、VS Code 扩展和 GitHub Action。
• 语法高亮 - 支持终端（ANSI）、HTML/CSS、JSON spans、LSP 语义令牌和 WASM 的方言感知高亮；使用 gosqlx highlight query.sql 或 gosqlx.HighlightANSI(sql)。
• 多方言 - 支持 8 种方言的专用语法：PostgreSQL、MySQL、MariaDB、SQL Server、Oracle、SQLite、Snowflake、ClickHouse。--dialect 标志和 WithDialect 接受 11 个名称：上述 8 种（postgresql、mysql、mariadb、sqlserver、oracle、sqlite、snowflake、clickhouse），以及 generic、bigquery 和 redshift。BigQuery 和 Redshift 没有特定方言的关键字集合（它们使用通用关键字），只有由功能支持控制的语法，例如 BigQuery 的 QUALIFY、PIVOT/UNPIVOT、FROM 中的 UNNEST 和 (struct).field 访问。
• 面向 AI - 提供 7 个工具的 MCP 服务、公开的远程端点、Streamable HTTP。
• 经过测试 - CI 中通过竞态检测器检查，SQL-99 覆盖率约为 80-85%（估算）。

文档

• 入门 - 5 分钟内解析你的第一条 SQL
• 使用指南 - 全面的模式和示例
• API 参考 - 完整的 API 文档
• CLI 指南 - 命令行工具参考
• SQL 兼容性 - 方言支持矩阵
• MCP 指南 - AI 助手集成
• 架构 - 系统设计深度解析
• 基准测试 - 性能数据和方法
• 更新日志 - 各版本的变更内容

参与贡献

GoSQLX 由像你这样的贡献者共同构建。无论是修复 Bug、添加新功能、改进文档，还是仅仅更正一个拼写错误，每一份贡献都很重要。

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

1. Fork 并从 main 创建分支
2. 编写测试 - 我们采用 TDD，并要求代码不存在竞态
3. 运行 task check - 提交 PR 前必须通过
4. 提交 PR - 我们会在 24 小时内审核

贡献指南 · 行为准则 · 治理

社区

有问题或想法：讨论区。发现 Bug 或希望添加功能：问题。

## License

Apache License 2.0 - see LICENSE for details.

---