makroumi/slowql
GitHub: makroumi/slowql
企业级 SQL 静态分析器，在代码进入生产环境前捕获性能反模式、安全漏洞、合规违规和成本陷阱。
Stars: 15 | Forks: 2
# SlowQL
**生产级 SQL 静态分析器，可防止性能灾难、安全漏洞和云成本爆炸。**
在糟糕的 SQL 进入生产环境之前将其拦截。SlowQL 是一款零依赖、离线的 SQL 分析器，能够捕捉性能反模式、安全漏洞、合规违规和成本陷阱——并提供开发者真正喜欢的精美终端体验。
## 🎯 为什么选择 SlowQL？
**SlowQL 能够预防的实际问题：**
| 问题 | 影响 | SlowQL 检测 |
|---------|--------|------------------|
| 在 1000 万行上使用 `SELECT *` | $$$ 云账单 | ✅ PERF-SCAN-001 |
| `DELETE FROM users` (无 WHERE) | 数据全部丢失 | ✅ REL-DATA-001 |
| `EXEC(@sql + @input)` | SQL 注入漏洞 | ✅ SEC-INJ-002 |
| `LIKE '%search%'` | 页面加载耗时 5 秒 | ✅ PERF-IDX-002 |
| 无限制的 PII 访问 | GDPR 违规 | ✅ COMP-GDPR-001 |
跨越 6 个关键维度的 **171 种检测模式**，在问题**进入生产环境之前**将其捕获。
## 📦 安装
```
# 推荐（隔离环境）
pipx install slowql
# 标准
pip install slowql
# 验证
slowql --version
```
要求：Python 3.11+ · Linux/macOS/Windows · 零外部依赖
## ⚡ 快速开始
### 分析 SQL 文件
```
# 创建测试文件
cat > test.sql << 'EOF'
SELECT * FROM users WHERE email LIKE '%@gmail.com';
DELETE FROM logs;
UPDATE users SET password = 'admin123' WHERE id = 1;
EOF
# 运行分析
slowql --input-file test.sql
```
### 交互模式
```
slowql
```
### CI/CD 模式
```
slowql --non-interactive --input-file sql/ --export json
```
## 🔍 检测能力
### 171 条活跃规则
| 维度 | 规则数 | 示例 |
|-----------|-------|----------|
| 🔒 安全 | 45 | SQL 注入、硬编码密钥、权限提升、xp_cmdshell |
| ⚡ 性能 | 39 | SELECT *、N+1、非 SARGable、笛卡尔积、深度分页 |
| 💰 成本 | 20 | 全表扫描、跨区域传输、无界聚合 |
| 🛡️ 可靠性 | 19 | 缺少 WHERE、无 CASCADE 的 DROP、事务安全性 |
| 📋 合规性 | 18 | GDPR 违规、PII 泄露、审计缺口 |
| 📝 质量 | 30 | 代码风格、命名、废弃语法 |
### 检测示例
#### 🔒 安全：SQL 注入
```
-- ❌ CRITICAL: Dynamic SQL
EXEC('SELECT * FROM users WHERE id = ' + @userId);
-- ❌ HIGH: Tautological condition
SELECT * FROM users WHERE username = 'admin' OR 1=1;
-- ❌ HIGH: Time-based injection
SELECT * FROM data WHERE id = 1 AND SLEEP(5);
```
*规则：SEC-INJ-002, SEC-INJ-003, SEC-INJ-004*
#### ⚡ 性能：索引杀手
```
-- ❌ Function on indexed column
SELECT * FROM users WHERE LOWER(email) = 'john@example.com';
-- ❌ Leading wildcard
SELECT * FROM users WHERE email LIKE '%@gmail.com';
-- ❌ Implicit type conversion
SELECT * FROM users WHERE user_id = '123'; -- user_id is INT
```
*规则：PERF-IDX-001, PERF-IDX-002, PERF-IDX-003*
#### 🛡️ 可靠性：数据丢失
```
-- ❌ CRITICAL: Deletes entire table
DELETE FROM users;
-- ❌ CRITICAL: Unbounded update
UPDATE users SET status = 'inactive';
```
*规则：REL-DATA-001, PERF-BATCH-001*
## 🎨 终端体验
### 功能特性
- 🎯 **健康评分**：0-100 分，配有可视化仪表
- 🔥 **严重性热力图**：问题分布矩阵
- 📊 **影响区域**：性能/安全/成本细分
- 🎭 **矩阵动画**：赛博朋克风格 UI
- ⌨️ **键盘导航**：方向键和快捷键
### 键盘快捷键
| 按键 | 操作 |
|-----|--------|
| ↑/↓ | 导航 |
| Enter | 选择 |
| q/Esc | 取消 |
| A | 分析更多 |
| E | 导出 |
| X | 退出 |
## 📊 导出格式
```
# 单一格式
slowql --input-file sql/ --export json
# 多种格式
slowql --input-file sql/ --export json html csv
# 自定义输出目录
slowql --input-file sql/ --export json --out ./reports
```
### JSON (CI/CD 集成)
```
{
"statistics": {
"total_issues": 28,
"by_severity": {"CRITICAL": 2, "HIGH": 10, "MEDIUM": 12, "LOW": 4},
"by_dimension": {"security": 8, "performance": 15, "cost": 3}
},
"issues": [...]
}
```
### HTML (可共享报告)
- 交互式单页报告
- 暗色霓虹主题
- 适于打印的布局
- 嵌入式统计数据
### CSV (电子表格分析)
```
severity,rule_id,dimension,message,impact,fix_guidance,location
CRITICAL,SEC-INJ-001,security,"SQL injection detected","Data breach","Use parameterized queries",line 5
```
## 🔧 CLI 参考
```
# 输入
slowql queries.sql # File
slowql --input-file sql/ # Directory
slowql --mode paste # Interactive paste
slowql --mode compose # Built-in editor
slowql --compare # Compare queries
# 输出
slowql --export json html csv # Export formats
slowql --out ./reports # Output directory
slowql --verbose # Detailed output
# UI
slowql --no-intro # Skip animation
slowql --fast # Minimal animations
slowql --non-interactive # CI/CD mode
```
## 🚀 CI/CD 集成
### GitHub Actions
```
name: SQL Quality Gate
on: [push, pull_request]
jobs:
sql-analysis:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- name: Install & Analyze
run: |
pip install slowql
slowql --non-interactive --input-file sql/ --export json
- name: Upload Reports
uses: actions/upload-artifact@v4
with:
name: slowql-reports
path: reports/
- name: Quality Gate
run: |
python -c "
import json, sys
from pathlib import Path
data = json.loads(sorted(Path('reports').glob('*.json'))[-1].read_text())
critical = data['statistics']['by_severity'].get('CRITICAL', 0)
if critical > 0:
print(f'❌ {critical} CRITICAL issues')
sys.exit(1)
print('✅ No critical issues')
"
```
### GitLab CI
```
sql-analysis:
stage: test
image: python:3.12-slim
script:
- pip install slowql
- slowql --non-interactive --input-file sql/ --export json
artifacts:
paths: [reports/]
```
### Pre-commit Hook
```
# .pre-commit-config.yaml
repos:
- repo: local
hooks:
- id: slowql
name: SlowQL
entry: slowql --non-interactive --export json
language: system
files: '\.(sql)$'
```
## 🐳 Docker
```
# 快速运行
docker run --rm -v "$PWD:/work" makroumi/slowql \
slowql --input-file /work/queries.sql
# 带导出
docker run --rm -v "$PWD:/work" makroumi/slowql \
slowql --input-file /work/sql/ --export json html --out /work/reports
```
### Docker Compose
```
version: '3.8'
services:
slowql:
image: makroumi/slowql:latest
volumes:
- ./sql:/work/sql:ro
- ./reports:/work/reports
command: slowql --non-interactive --input-file sql/ --export json html --out reports/
```
## 🏗️ 架构
### 性能
| 文件大小 | 查询数 | 耗时 | 内存 |
|-----------|---------|------|--------|
| 小型 | < 100 | < 1s | ~50MB |
| 中型 | 100-1K | 1-5s | ~80MB |
| 大型 | 1K-10K | 5-30s | ~150MB |
### 隐私
- ✅ **零网络调用** - 100% 离线
- ✅ **无遥测** - 零数据收集
- ✅ **本地处理** - SQL 永不离开您的机器
- ✅ **开源** - 完全可审计
## 🛠️ 开发
```
# 设置
git clone https://github.com/makroumi/slowql.git
cd slowql
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
# 验证
pytest -q # 873 tests
# 质量
ruff check . && mypy src/slowql/
```
### 项目结构
```
src/slowql/
├── analyzers/ # 6 dimension analyzers
├── rules/ # 171 detection rules
│ ├── security/ # 45 rules
│ ├── performance/# 39 rules
│ ├── cost/ # 20 rules
│ ├── reliability/# 19 rules
│ ├── compliance/ # 18 rules
│ ├── quality/ # 30 rules
├── cli/ # Terminal UI
├── core/ # Analysis engine
├── parser/ # SQL parser
└── reporters/ # JSON/HTML/CSV
```
### 添加规则
```
# src/slowql/rules/security/my_rule.py
from slowql.rules.base import PatternRule
from slowql.core.models import Severity, Dimension
class MyRule(PatternRule):
id = "SEC-CUSTOM-001"
name = "My Custom Check"
severity = Severity.HIGH
dimension = Dimension.SECURITY
pattern = r"\bDANGEROUS\b"
message_template = "Dangerous pattern: {match}"
```
## 🗺️ 路线图
| 版本 | 目标 | 功能 |
|---------|--------|----------|
| v1.4.0 | ✅ 当前 | 171 条规则、模块化架构、高级 UI |
| v1.5.0 | 2026 年 Q2 | VS Code 扩展、行内分析 |
| v1.6.0 | 2026 年 Q3 | 高级 AST、查询复杂度指标 |
| v2.0.0 | 2026 年 Q4 | 企业版：自定义规则包、团队仪表盘 |
## 🤝 贡献
```
# Fork → Clone → Branch
git checkout -b feat/amazing-feature
# 开发
pip install -e ".[dev]"
pytest -q
ruff check .
# 提交 PR
See CONTRIBUTING.md for full guidelines.
```
## 📜 许可证
Apache 2.0 — 可免费用于商业和非商业用途。详见 LICENSE。
## 📞 支持
- 🐛 **问题反馈**：[GitHub Issues](https://github.com/makroumi/slowql/issues)
- 💬 **讨论交流**：[GitHub Discussions](https://github.com/makroumi/slowql/discussions)
在糟糕的 SQL 让您破费之前将其拦截。
由 @makroumi 用 ❤️ 制作
⬆ 回到顶部
*祝您 SQL 分析愉快！ 🎯*
标签：CLI应用, DevSecOps, Docker, FinOps, LNA, Python, SQL分析器, SQL审计, SQL注入检测, 上游代理, 云成本管理, 代码安全, 企业级工具, 反模式检测, 威胁情报, 安全防御评估, 属性图, 开发者工具, 性能优化, 数据隐私, 无后门, 检测绕过, 漏洞枚举, 离线分析, 自动化安全运营, 请求拦截, 质量保证, 逆向工具, 错误基检测, 静态代码分析