ajitpratap0/GoSQLX

# GoSQLX ## 概述 GoSQLX 是一个为生产环境设计的高性能 SQL 解析库。它提供零拷贝词法分析、智能对象池和全面的 SQL 方言支持，同时保持简单、符合 Go 语言习惯的 API。 ### 核心特性 - **极速**：通过 Token 类型重构实现约 50% 的解析速度提升；峰值吞吐量达 125 万+ ops/sec - **内存高效**：通过智能对象池减少 60-80% 的内存占用 - **线程安全**：无竞态条件，线性扩展至 128+ 核心，未检测到任何竞态条件 - **多方言引擎** (v1.8.0)：通过 `ParseWithDialect()` 提供一流的方言支持 —— PostgreSQL、MySQL、SQL Server、Oracle、SQLite、Snowflake - **MySQL 语法** (v1.8.0)：SHOW、DESCRIBE、REPLACE INTO、ON DUPLICATE KEY UPDATE、GROUP_CONCAT、MATCH AGAINST、REGEXP/RLIKE - **查询转换 API** (v1.8.0)：可编程的 SQL 重写 —— 通过可组合规则添加 WHERE 子句、列、JOIN、分页（`pkg/transform/`） - **WASM 演练场** (v1.8.0)：通过 WebAssembly 在浏览器中进行 SQL 解析、格式化和 Lint - **注释保留** (v1.8.0)：SQL 注释在解析-格式化往返过程中保持不变 - **AST 转 SQL 往返** (v1.8.0)：所有 AST 节点上的 `SQL()` 方法支持完整序列化 - **基于 AST 的格式化器** (v1.8.0)：可配置的 SQL 格式化器，提供 CompactStyle/ReadableStyle 预设 - **错误恢复** (v1.8.0)：通过 `ParseWithRecovery()` 进行多错误解析，提供 IDE 级别的诊断 - **完整的 JOIN 支持**：所有 JOIN 类型（INNER/LEFT/RIGHT/FULL OUTER/CROSS/NATURAL），具有正确的树逻辑 - **高级 SQL 特性**：支持 RECURSIVE 的 CTE、集合操作（UNION/EXCEPT/INTERSECT） - **窗口函数**：完整的 SQL-99 窗口函数支持，包括 OVER 子句、PARTITION BY、ORDER BY、帧规范 - **MERGE 语句**：完整的 SQL:2003 MERGE 支持，包含 WHEN MATCHED/NOT MATCHED 子句 - **分组操作**：GROUPING SETS、ROLLUP、CUBE（SQL-99 T431） - **PostgreSQL 扩展**：LATERAL JOIN、DISTINCT ON、FILTER 子句、JSON/JSONB 操作符、聚合 ORDER BY、`::` 类型转换、UPSERT、美元符号引用字符串 - **SQL 注入检测**：内置安全扫描器（`pkg/sql/security`），支持 LIKE 注入、盲注、永真式检测 - **Unicode 支持**：完整的 UTF-8 国际化 SQL 支持 - **零拷贝**：直接字节切片操作，延迟 <1μs - **智能错误**：结构化错误代码，包含拼写错误检测、上下文高亮和有用提示 - **Python 绑定**：[PyGoSQLX](python/README.md) —— 通过 ctypes FFI 在 Python 中使用 GoSQLX，比纯 Python 解析器快 100 倍以上 - **MCP Server** (v1.10.0)：`gosqlx-mcp` 将所有 7 个 SQL 工具作为 [Model Context Protocol](https://modelcontextprotocol.io) 工具通过可流式传输的 HTTP 暴露 —— 将 GoSQLX 集成到 Claude、Cursor 和任何兼容 MCP 的 AI 助手中 - **生产就绪**：经过实战测试，未检测到竞态条件，SQL-99 合规性约 85%，Apache-2.0 许可 ### 性能与质量亮点 (v1.10.0) ### v1.10.0 新增内容 ### 项目统计 ## 安装 ### 库安装 ``` go get github.com/ajitpratap0/GoSQLX ``` ### CLI 安装 ``` # 安装 CLI 工具 go install github.com/ajitpratap0/GoSQLX/cmd/gosqlx@latest # 或从源码构建 git clone https://github.com/ajitpratap0/GoSQLX.git cd GoSQLX go build -o gosqlx ./cmd/gosqlx ``` ### Python 绑定 通过 ctypes FFI 在 Python 中以原生性能使用 GoSQLX： ``` # 构建共享库（需要 Go 1.21+） cd pkg/cbinding && ./build.sh && cd ../.. # 安装 Python 包 cd python && pip install . ``` ``` import pygosqlx result = pygosqlx.parse("SELECT * FROM users WHERE active = true") print(result.statement_types) # ['SELECT'] tables = pygosqlx.extract_tables("SELECT * FROM users u JOIN orders o ON u.id = o.user_id") print(tables) # ['users', 'orders'] ``` 查看完整的 [PyGoSQLX 文档](python/README.md) 了解完整 API。 ### MCP Server 在任何兼容 MCP 的 AI 助手中使用 GoSQLX SQL 工具： ``` go install github.com/ajitpratap0/GoSQLX/cmd/gosqlx-mcp@latest gosqlx-mcp # starts on 127.0.0.1:8080 ``` 查看完整的 [MCP Server 指南](docs/MCP_GUIDE.md) 了解配置、认证和 AI 助手集成。 **系统要求：** - Go 1.23 或更高版本 - Python 3.8+（用于 Python 绑定） - Go 库无外部依赖 ## 快速开始 ### CLI 使用 **内联 SQL：** ``` # 验证 SQL 语法 gosqlx validate "SELECT * FROM users WHERE active = true" # 分析 SQL 结构和复杂度 gosqlx analyze "SELECT COUNT(*) FROM orders GROUP BY status" ``` **文件处理：** ``` # 格式化 SQL 文件（智能缩进） gosqlx format -i query.sql # 将 SQL 解析为 AST 表示 gosqlx parse -f json complex_query.sql ``` **管道/标准输入：** ``` cat query.sql | gosqlx format # Format from stdin echo "SELECT * FROM users" | gosqlx validate # Validate from pipe gosqlx format query.sql | gosqlx validate # Chain commands cat *.sql | gosqlx format | tee formatted.sql # Pipeline composition ``` **管道/标准输入支持** (v1.6.0+)： ``` # 自动检测管道输入 echo "SELECT * FROM users" | gosqlx validate cat query.sql | gosqlx format cat complex.sql | gosqlx analyze --security # 显式 stdin 标记 gosqlx validate - gosqlx format - < query.sql # 输入重定向 gosqlx validate < query.sql gosqlx parse < complex_query.sql # 完整管道链 cat query.sql | gosqlx format | gosqlx validate echo "select * from users" | gosqlx format > formatted.sql find . -name "*.sql" -exec cat {} \; | gosqlx validate # Windows PowerShell 同样适用！ Get-Content query.sql | gosqlx format "SELECT * FROM users" | gosqlx validate ``` **跨平台管道示例：** ``` # Unix/Linux/macOS cat query.sql | gosqlx format | tee formatted.sql | gosqlx validate echo "SELECT 1" | gosqlx validate && echo "Valid!" # Windows PowerShell Get-Content query.sql | gosqlx format | Set-Content formatted.sql "SELECT * FROM users" | gosqlx validate # Git hooks (pre-commit) git diff --cached --name-only --diff-filter=ACM "*.sql" | \ xargs cat | gosqlx validate --quiet ``` **语言服务器协议 (LSP)** (v1.6.0+)： ``` # 启动 LSP server 用于 IDE 集成 gosqlx lsp # 带 debug 日志 gosqlx lsp --log /tmp/gosqlx-lsp.log ``` LSP 服务器为 IDE 提供实时的 SQL 智能： - **诊断**：带有位置信息的实时语法错误检测 - **悬停**：60+ SQL 关键字的文档 - **补全**：100+ SQL 关键字、函数和 22 个代码片段 - **格式化**：通过 `textDocument/formatting` 进行 SQL 代码格式化 - **文档符号**：SQL 语句大纲导航 - **签名帮助**：20+ SQL 函数的签名 - **代码操作**：快速修复（添加分号、大写关键字） **Linting** (v1.6.0+)： ``` # 运行内置 linter 规则 gosqlx lint query.sql # 自动修复 gosqlx lint --fix query.sql # 特定规则 gosqlx lint --rules L001,L002,L003 query.sql ``` 可用规则 (L001-L010)： - `L001`：尾部空白（自动修复） - `L002`：混合缩进（自动修复） - `L003`：连续空行（自动修复） - `L004`：缩进深度 - `L005`：行长度 - `L006`：列对齐 - `L007`：关键字大小写（自动修复） - `L008`：逗号位置 - `L009`：别名一致性 - `L010`：冗余空白（自动修复） **IDE 集成：** ``` // VSCode settings.json { "gosqlx.lsp.enable": true, "gosqlx.lsp.path": "gosqlx" } ``` ``` -- Neovim (nvim-lspconfig) require('lspconfig.configs').gosqlx = { default_config = { cmd = { 'gosqlx', 'lsp' }, filetypes = { 'sql' }, root_dir = function() return vim.fn.getcwd() end, }, } require('lspconfig').gosqlx.setup{} ``` ### 库使用 - 简单 API GoSQLX 提供了一个简单的高级 API，为您处理所有复杂性： ``` 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) } fmt.Printf("Successfully parsed %d statement(s)\n", len(ast.Statements)) } ``` **就是这样！** 只需 3 行代码。无需池管理，无需手动清理 —— 一切都已为您处理。 ### 更多示例 ``` // Validate SQL without parsing if err := gosqlx.Validate("SELECT * FROM users"); err != nil { fmt.Println("Invalid SQL:", err) } // Parse multiple queries efficiently queries := []string{ "SELECT * FROM users", "SELECT * FROM orders", } asts, err := gosqlx.ParseMultiple(queries) // Parse with timeout for long queries ast, err := gosqlx.ParseWithTimeout(sql, 5*time.Second) // Parse from byte slice (zero-copy) ast, err := gosqlx.ParseBytes([]byte("SELECT * FROM users")) ``` ### 高级用法 - 底层 API 对于需要精细控制的性能关键型代码，请使用底层 API： ``` package main import ( "fmt" "github.com/ajitpratap0/GoSQLX/pkg/sql/tokenizer" "github.com/ajitpratap0/GoSQLX/pkg/sql/parser" ) func main() { // Get tokenizer from pool (always return it!) tkz := tokenizer.GetTokenizer() defer tokenizer.PutTokenizer(tkz) // Tokenize SQL sql := "SELECT id, name FROM users WHERE age > 18" tokens, err := tkz.Tokenize([]byte(sql)) if err != nil { panic(err) } // Convert tokens converter := parser.NewTokenConverter() result, err := converter.Convert(tokens) if err != nil { panic(err) } // Parse to AST p := parser.NewParser() defer p.Release() ast, err := p.Parse(result.Tokens) if err != nil { panic(err) } fmt.Printf("Parsed %d statement(s)\n", len(ast.Statements)) fmt.Printf("Statement type: %T\n", ast.Statements[0]) } ``` ## 文档 ### 综合指南 | 指南 | 描述 | |-------|-------------| | [**指南**](docs/GETTING_STARTED.md) | 5 分钟快速上手 | | [**对比指南**](docs/COMPARISON.md) | GoSQLX vs SQLFluff, JSQLParser, pg_query | | [**CLI 指南**](docs/CLI_GUIDE.md) | 完整的 CLI 文档和使用示例 | | [**API 参考**](docs/API_REFERENCE.md) | 包含示例的完整 API 文档 | | [**使用指南**](docs/USAGE_GUIDE.md) | 详细模式与最佳实践 | | [**架构**](docs/ARCHITECTURE.md) | 系统设计和内部架构 | | [**Python 绑定**](python/README.md) | PyGoSQLX —— Python API、安装和示例 | | [**MCP Server 指南**](docs/MCP_GUIDE.md) | `gosqlx-mcp` —— 用于 AI 助手集成的 7 个 SQL 工具 | | [**故障排除**](docs/TROUBLESHOOTING.md) | 常见问题与解决方案 | ### 入门 | 文档 | 用途 | |----------|---------| | [**生产指南**](docs/PRODUCTION_GUIDE.md) | 部署与监控 | | [**SQL 兼容性**](docs/SQL_COMPATIBILITY.md) | 方言支持矩阵 | | [**迁移指南**](docs/MIGRATION.md) | v1.7.0 → v1.8.0 重大变更 | | [**安全分析**](docs/SECURITY.md) | 安全评估 | | [**LSP 指南**](docs/LSP_GUIDE.md) | LSP 服务器与 IDE 集成 | | [**Lint 规则**](docs/LINTING_RULES.md) | 所有 10 条 Lint 规则参考 | | [**错误代码**](docs/ERROR_CODES.md) | 错误代码参考 (E1001-E3004) | | [**升级指南**](docs/UPGRADE_GUIDE.md) | 版本升级说明 | | [**示例**](examples/) | 可运行的代码示例（包括转换 API） | ### 快速链接 - [安装与设置](docs/USAGE_GUIDE.md#getting-started) - [基本用法](docs/USAGE_GUIDE.md#basic-usage) - [高级模式](docs/USAGE_GUIDE.md#advanced-patterns) - [性能调优](docs/PRODUCTION_GUIDE.md#performance-optimization) - [错误处理](docs/TROUBLESHOOTING.md#error-messages) - [常见问题](docs/TROUBLESHOOTING.md#faq) ### 高级 SQL 特性 GoSQLX 支持公用表表达式 和集合操作，以及完整的 JOIN 支持： #### 公用表表达式 ``` // Simple CTE sql := ` WITH sales_summary AS ( SELECT region, SUM(amount) as total FROM sales GROUP BY region ) SELECT region FROM sales_summary WHERE total > 1000 ` // Recursive CTE for hierarchical data sql := ` WITH RECURSIVE employee_tree AS ( SELECT employee_id, manager_id, name FROM employees WHERE manager_id IS NULL UNION ALL SELECT e.employee_id, e.manager_id, e.name FROM employees e JOIN employee_tree et ON e.manager_id = et.employee_id ) SELECT * FROM employee_tree ` // Multiple CTEs in single query sql := ` WITH regional AS (SELECT region, total FROM sales), summary AS (SELECT region FROM regional WHERE total > 1000) SELECT * FROM summary ` ``` #### 集合操作 ``` // UNION - combine results with deduplication sql := "SELECT name FROM users UNION SELECT name FROM customers" // UNION ALL - combine results preserving duplicates sql := "SELECT id FROM orders UNION ALL SELECT id FROM invoices" // EXCEPT - set difference sql := "SELECT product FROM inventory EXCEPT SELECT product FROM discontinued" // INTERSECT - set intersection sql := "SELECT customer_id FROM orders INTERSECT SELECT customer_id FROM payments" // Left-associative parsing for multiple operations sql := "SELECT a FROM t1 UNION SELECT b FROM t2 INTERSECT SELECT c FROM t3" // Parsed as: (SELECT a FROM t1 UNION SELECT b FROM t2) INTERSECT SELECT c FROM t3 ``` #### 完整的 JOIN 支持 GoSQLX 支持所有 JOIN 类型，并具有正确的左结合树逻辑： ``` // Complex JOIN query with multiple table relationships sql := ` SELECT u.name, o.order_date, p.product_name, c.category_name FROM users u LEFT JOIN orders o ON u.id = o.user_id INNER JOIN products p ON o.product_id = p.id RIGHT JOIN categories c ON p.category_id = c.id WHERE u.active = true ORDER BY o.order_date DESC ` // Parse with the simple API (recommended) tree, err := gosqlx.Parse(sql) if err != nil { panic(err) } // Access JOIN information if selectStmt, ok := tree.Statements[0].(*ast.SelectStatement); ok { fmt.Printf("Found %d JOINs:\n", len(selectStmt.Joins)) for i, join := range selectStmt.Joins { fmt.Printf("JOIN %d: %s (left: %s, right: %s)\n", i+1, join.Type, join.Left.Name, join.Right.Name) } } ``` **支持的 JOIN 类型：** - ✅ `INNER JOIN` - 标准内连接 - ✅ `LEFT JOIN` / `LEFT OUTER JOIN` - 左外连接 - ✅ `RIGHT JOIN` / `RIGHT OUTER JOIN` - 右外连接 - ✅ `FULL JOIN` / `FULL OUTER JOIN` - 全外连接 - ✅ `CROSS JOIN` - 笛卡尔积连接 - ✅ `NATURAL JOIN` - 自然连接（隐式 ON 子句） - ✅ `USING (column)` - 单列 USING 子句 ### 高级 SQL 特性 (v1.4+) #### MERGE 语句 (SQL:2003 F312) ``` sql := ` MERGE INTO target_table t USING source_table s ON t.id = s.id WHEN MATCHED THEN UPDATE SET t.name = s.name, t.value = s.value WHEN NOT MATCHED THEN INSERT (id, name, value) VALUES (s.id, s.name, s.value) ` ast, err := gosqlx.Parse(sql) ``` #### GROUPING SETS, ROLLUP, CUBE (SQL-99 T431) ``` // GROUPING SETS - explicit grouping combinations sql := `SELECT region, product, SUM(sales) FROM orders GROUP BY GROUPING SETS ((region), (product), (region, product), ())` // ROLLUP - hierarchical subtotals sql := `SELECT year, quarter, month, SUM(revenue) FROM sales GROUP BY ROLLUP (year, quarter, month)` // CUBE - all possible combinations sql := `SELECT region, product, SUM(amount) FROM sales GROUP BY CUBE (region, product)` ``` #### 物化视图 ``` // Create materialized view sql := `CREATE MATERIALIZED VIEW sales_summary AS SELECT region, SUM(amount) as total FROM sales GROUP BY region` // Refresh materialized view sql := `REFRESH MATERIALIZED VIEW CONCURRENTLY sales_summary` // Drop materialized view sql := `DROP MATERIALIZED VIEW IF EXISTS sales_summary` ``` #### SQL 注入检测 ``` import "github.com/ajitpratap0/GoSQLX/pkg/sql/security" // Create scanner scanner := security.NewScanner() // Scan for injection patterns result := scanner.Scan(ast) if result.HasCritical() { fmt.Printf("Found %d critical issues!\n", result.CriticalCount) for _, finding := range result.Findings { fmt.Printf(" [%s] %s: %s\n", finding.Severity, finding.Pattern, finding.Description) } } // Detected patterns include: // - Tautology (1=1, 'a'='a') // - UNION-based injection // - Time-based blind (SLEEP, WAITFOR DELAY) // - Comment bypass (--, /**/) // - Stacked queries // - Dangerous functions (xp_cmdshell, LOAD_FILE) ``` #### 表达式操作符 (BETWEEN, IN, LIKE, IS NULL) ``` // BETWEEN with expressions sql := `SELECT * FROM orders WHERE amount BETWEEN 100 AND 500` // IN with subquery sql := `SELECT * FROM users WHERE id IN (SELECT user_id FROM admins)` // LIKE with pattern matching sql := `SELECT * FROM products WHERE name LIKE '%widget%'` // IS NULL / IS NOT NULL sql := `SELECT * FROM users WHERE deleted_at IS NULL` // NULLS FIRST/LAST ordering (SQL-99 F851) sql := `SELECT * FROM users ORDER BY last_login DESC NULLS LAST` ``` #### PostgreSQL 特有特性 (v1.6+) **LATERAL JOIN** - FROM 子句中的相关子查询： ``` // LATERAL allows referencing columns from preceding tables sql := ` SELECT u.name, recent_orders.order_date, recent_orders.total FROM users u LEFT JOIN LATERAL ( SELECT order_date, total FROM orders WHERE user_id = u.id ORDER BY order_date DESC LIMIT 1 ) AS recent_orders ON true ` ast, err := gosqlx.Parse(sql) ``` **聚合内的 ORDER BY** - 有序集合函数： ``` // STRING_AGG with ORDER BY sql := `SELECT STRING_AGG(name, ', ' ORDER BY name DESC NULLS LAST) FROM users` // ARRAY_AGG with ORDER BY sql := `SELECT ARRAY_AGG(value ORDER BY created_at, priority DESC) FROM items` // JSON_AGG with ORDER BY sql := `SELECT JSON_AGG(employee_data ORDER BY hire_date) FROM employees` // Multiple aggregates with different orderings sql := ` SELECT department, STRING_AGG(name, '; ' ORDER BY name ASC NULLS FIRST) AS employee_names, ARRAY_AGG(salary ORDER BY salary DESC) AS salaries FROM employees GROUP BY department ` ast, err := gosqlx.Parse(sql) ``` **JSON/JSONB 操作符** - PostgreSQL JSON 支持： ``` // Arrow operators for field access sql := `SELECT data -> 'user' -> 'profile' ->> 'email' FROM users` // Path operators for nested access sql := `SELECT data #> '{address,city}', data #>> '{address,zipcode}' FROM users` // Containment operators sql := `SELECT * FROM users WHERE data @> '{"active": true}'` sql := `SELECT * FROM users WHERE '{"admin": true}' <@ data` // Combined JSON operators in complex queries sql := ` SELECT u.id, u.data ->> 'name' AS user_name, u.data -> 'settings' ->> 'theme' AS theme FROM users u WHERE u.data @> '{"verified": true}' AND u.data ->> 'status' = 'active' ` ast, err := gosqlx.Parse(sql) ``` **DISTINCT ON** - PostgreSQL 唯一行选择： ``` // Select first row per group based on ordering sql := ` SELECT DISTINCT ON (user_id) user_id, created_at, status FROM orders ORDER BY user_id, created_at DESC ` ast, err := gosqlx.Parse(sql) ``` **FILTER 子句** - 条件聚合： ``` // COUNT with FILTER sql := ` SELECT COUNT(*) AS total_orders, COUNT(*) FILTER (WHERE status = 'completed') AS completed_orders, SUM(amount) FILTER (WHERE region = 'US') AS us_revenue FROM orders ` ast, err := gosqlx.Parse(sql) ``` ## 示例 ### 多方言支持 (v1.8.0) ``` import "github.com/ajitpratap0/GoSQLX/pkg/sql/parser" // Parse with explicit dialect ast, err := parser.ParseWithDialect("SHOW TABLES", "mysql") // MySQL-specific syntax ast, err = parser.ParseWithDialect(` INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com') ON DUPLICATE KEY UPDATE email = VALUES(email) `, "mysql") // PostgreSQL (default) ast, err = parser.ParseWithDialect(` SELECT * FROM users WHERE tags @> ARRAY['admin'] `, "postgresql") // CLI with dialect flag // gosqlx validate --dialect mysql "SHOW TABLES" ``` ### 查询转换 API (v1.8.0) ``` import "github.com/ajitpratap0/GoSQLX/pkg/transform" // Parse SQL, add multi-tenant WHERE filter stmt, _ := transform.ParseSQL("SELECT * FROM orders") transform.AddWhere(stmt, "tenant_id = 42") sql := transform.FormatSQL(stmt) // SELECT * FROM orders WHERE tenant_id = 42 // Composable rules transform.Apply(stmt, transform.AddWhereRule("active = true"), transform.SetLimitRule(100), transform.AddOrderByRule("created_at", "DESC"), ) ``` ### Unicode 和国际化 SQL ``` // Japanese sql := `SELECT "名前", "年齢" FROM "ユーザー"` // Russian sql := `SELECT "имя", "возраст" FROM "пользователи"` // Arabic sql := `SELECT "الاسم", "العمر" FROM "المستخدمون"` // Emoji support sql := `SELECT * FROM users WHERE status = '🚀'` ``` ### 并发处理 ``` func ProcessConcurrently(queries []string) { var wg sync.WaitGroup for _, sql := range queries { wg.Add(1) go func(query string) { defer wg.Done() // Each goroutine gets its own tokenizer tkz := tokenizer.GetTokenizer() defer tokenizer.PutTokenizer(tkz) tokens, _ := tkz.Tokenize([]byte(query)) // Process tokens... }(sql) } wg.Wait() } ``` ## 性能 ### v1.0.0 性能改进 | 指标 | 之前 | **v1.0.0** | 改进 | |--------|----------|------------|-------------| | **持续吞吐量** | 2.2M ops/s | **946K+ ops/s** | **生产级** ✅ | | **峰值吞吐量** | 2.2M ops/s | **1.25M+ ops/s** | **增强** ✅ | | **Token 处理** | 8M tokens/s | **8M+ tokens/s** | **保持** ✅ | | **简单查询延迟** | 200ns | **<280ns** | **优化** ✅ | | **复杂查询延迟** | N/A | **<1μs (CTE/Set Ops)** | **新功能** ✅ | | **内存使用** | 基准 | **减少 60-80%** | **-70%** ✅ | | **SQL-92 合规性** | 40% | **~70%** | **+75%** ✅ | ### 最新基准测试结果 ``` BenchmarkParserSustainedLoad-16 946,583 1,057 ns/op 1,847 B/op 23 allocs/op BenchmarkParserThroughput-16 1,252,833 798 ns/op 1,452 B/op 18 allocs/op BenchmarkParserSimpleSelect-16 3,571,428 279 ns/op 536 B/op 9 allocs/op BenchmarkParserComplexSelect-16 985,221 1,014 ns/op 2,184 B/op 31 allocs/op BenchmarkCTE/SimpleCTE-16 524,933 1,891 ns/op 3,847 B/op 52 allocs/op BenchmarkCTE/RecursiveCTE-16 387,654 2,735 ns/op 5,293 B/op 71 allocs/op BenchmarkSetOperations/UNION-16 445,782 2,234 ns/op 4,156 B/op 58 allocs/op BenchmarkTokensPerSecond-16 815,439 1,378 ns/op 8,847,625 tokens/sec ``` ### 性能特征 | 指标 | 值 | 详情 | |--------|-------|---------| | **持续吞吐量** | **946K+ ops/sec** | 30s 负载测试 | | **峰值吞吐量** | **1.25M+ ops/sec** | 并发 Goroutine | | **Token 速率** | **8M+ tokens/sec** | 持续处理 | | **简单查询延迟** | **<280ns** | 基本 SELECT (p50) | | **复杂查询延迟** | **<1μs** | CTE/集合操作 | | **内存** | **1.8KB/query** | 带池化的复杂 SQL | | **扩展性** | **线性至 128+** | 完美的并发性 | | **池效率** | **95%+ 命中率** | 有效的重用 | 运行 `go test -bench=. -benchmem ./pkg/...` 进行详细的性能分析。 ## 测试 ``` # 运行所有测试（含 race 检测） go test -race ./... # 运行基准测试 go test -bench=. -benchmem ./... # 生成覆盖率报告 go test -coverprofile=coverage.out ./... go tool cover -html=coverage.out # 运行特定测试套件 go test -v ./pkg/sql/tokenizer/ go test -v ./pkg/sql/parser/ ``` ## 项目结构 ``` GoSQLX/ ├── cmd/gosqlx/ # CLI tool (validate, format, parse, analyze, lint, lsp, optimize, action) │ ├── cmd/ # Core CLI commands │ └── internal/ # Extracted sub-packages (lspcmd, actioncmd, optimizecmd, cmdutil) ├── pkg/ │ ├── models/ # Core data structures (tokens, spans, locations) │ ├── errors/ # Structured error handling with position tracking │ ├── config/ # Configuration management (YAML/JSON/env) │ ├── metrics/ # Performance monitoring and observability │ ├── gosqlx/ # High-level simple API (recommended entry point) │ ├── cbinding/ # C shared library bindings (for Python/FFI) │ ├── linter/ # SQL linting engine with 10 rules (L001-L010) │ ├── lsp/ # Language Server Protocol server for IDEs │ ├── transform/ # Query rewriting/transform API (v1.8.0) │ ├── formatter/ # Public SQL formatter package (v1.8.0) │ ├── advisor/ # Query optimization advisor with 12 rules │ ├── schema/ # Schema-aware validation │ ├── compatibility/ # API stability testing │ └── sql/ │ ├── tokenizer/ # Zero-copy lexical analysis with dialect support │ ├── parser/ # Recursive descent parser with dialect modes │ ├── ast/ # Abstract syntax tree with SQL() serialization │ ├── token/ # Token type definitions (int-based, v1.8.0) │ ├── keywords/ # Multi-dialect SQL keyword definitions │ ├── security/ # SQL injection detection with fuzz testing │ └── monitor/ # SQL monitoring utilities ├── wasm/ # WebAssembly build + browser playground (v1.8.0) ├── python/ # PyGoSQLX - Python bindings via ctypes FFI ├── examples/ # Usage examples (including transform examples) ├── docs/ # Comprehensive documentation (20+ guides) └── vscode-extension/ # Official VSCode extension ``` ## 开发 ### 前置条件 - Go 1.21+ - [Task](https://taskfile.dev) - 任务运行器（安装：`go install github.com/go-task/task/v3/cmd/task@latest`） - golangci-lint, staticcheck（用于代码质量，安装：`task deps:tools`） ### 任务运行器 本项目使用 [Task](https://taskfile.dev) 作为任务运行器。安装方式： ``` go install github.com/go-task/task/v3/cmd/task@latest # 或：brew install go-task (macOS) ``` ### 构建 ``` # 显示所有可用任务 task # 构建项目 task build # 构建 CLI 二进制文件 task build:cli # 全局安装 CLI task install # 运行所有质量检查 task quality # 运行所有测试 task test # 运行测试（含 race 检测）（推荐） task test:race # 清理构建产物 task clean ``` ### 代码质量 ``` # 格式化代码 task fmt # 运行 go vet task vet # 运行 golangci-lint task lint # 运行所有质量检查 (fmt, vet, lint) task quality # 完整 CI 检查（格式化、vet、lint、test:race） task check ``` ## 贡献 我们欢迎您的贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南。 ### 如何贡献 1. Fork 本仓库 2. 创建一个功能分支 (`git checkout -b feature/amazing-feature`) 3. 提交您的更改 (`git commit -m 'Add amazing feature'`) 4. 推送到分支 (`git push origin feature/amazing-feature`) 5. 打开一个 Pull Request ### 开发指南 - 为新功能编写测试 - 确保所有测试通过竞态检测 - 遵循 Go 语言习惯和最佳实践 - 更新 API 更改的文档 - 为性能关键型代码添加基准测试 ## 路线图 ### 阶段 5：方言引擎、查询转换与工具 - v1.8.0 ✅ - ✅ **方言模式引擎** - `ParseWithDialect()`、`--dialect` CLI 标志、6 种方言 - ✅ **MySQL 语法** - SHOW、DESCRIBE、REPLACE INTO、ON DUPLICATE KEY UPDATE、GROUP_CONCAT、MATCH AGAINST、REGEXP - ✅ **查询转换 API** - `pkg/transform/` 支持 WHERE、列、JOIN、表、LIMIT/OFFSET、ORDER BY 操作 - ✅ **WASM 演练场** - 通过 WebAssembly 在浏览器中进行 SQL 解析、格式化、Lint - ✅ **注释保留** - SQL 注释在解析-格式化往返过程中保持不变 - ✅ **AST 转 SQL 序列化** - 所有 AST 节点上的 `SQL()` 方法支持往返 - ✅ **基于 AST 的格式化器** - CompactStyle/ReadableStyle 预设，支持关键字大小写选项 - ✅ **DDL 格式化器** - ALTER TABLE、CREATE INDEX/VIEW、DROP、TRUNCATE 的 Format() - ✅ **错误恢复** - `ParseWithRecovery()` 用于多错误 IDE 诊断 - ✅ **美元符号引用字符串** - PostgreSQL `$$body$$` Tokenizer 支持 - ✅ **Token 类型重构** - 通过 O(1) 整数 Token 比较实现约 50% 的解析速度提升 - ✅ **查询顾问** - 12 条优化规则（OPT-001 至 OPT-012） - ✅ **模式验证** - NOT NULL、类型兼容性、外键验证 - ✅ **Snowflake 方言** - 关键字检测和支持 - ✅ **Apache-2.0 许可证** - 从 AGPL 重新许可 ### 阶段 4：解析器增强与 PostgreSQL 扩展 - v1.7.0 ✅ - ✅ **模式限定名称** - 所有 DML/DDL 中的 `schema.table` 和 `db.schema.table` - ✅ **PostgreSQL 类型转换** - 用于类型转换的 `::` 操作符 - ✅ **UPSERT** - `INSERT ... ON CONFLICT DO UPDATE/NOTHING` - ✅ **ARRAY 构造器** - `ARRAY[1, 2, 3]` 支持下标/切片操作 - ✅ **正则表达式操作符** - `~`、`~*`、`!~`、`!~*` 用于模式匹配 - ✅ **INTERVAL 表达式** - 时间字面量 - ✅ **FOR UPDATE/SHARE** - 行级锁定子句 - ✅ **位置参数** - `$1`、`$2` 风格的占位符 - ✅ **Python 绑定** - [PyGoSQLX](python/README.md) 支持 ctypes FFI、线程安全、内存安全 ### 阶段 6：高级优化与模式智能 - v2.0.0 📋 - 📋 **高级查询成本估算** - 扩展的复杂性分析 - 📋 **模式 Diff** - 比较并生成迁移脚本 - 📋 **实体关系提取** - 从 DDL 生成 ER 图 - 📋 **存储过程** - CREATE PROCEDURE/FUNCTION 解析 - 📋 **PL/pgSQL** - PostgreSQL 过程语言 - 📋 **T-SQL 扩展** - PIVOT/UNPIVOT、CROSS/OUTER APPLY 解析 查看 [ARCHITECTURE.md](docs/ARCHITECTURE.md) 了解详细的系统设计，[CHANGELOG.md](CHANGELOG.md) 了解版本历史 ## 社区与支持 ## 贡献者 ## 使用案例 ## 谁在使用 GoSQLX ## 项目指标 ## 支持本项目 ## 许可证

由 GoSQLX 团队用 ❤️ 构建

_{版权所有 © 2024-2026 GoSQLX。保留所有权利。}