Metadata-Version: 2.4
Name: dbskiter
Version: 3.0.0
Summary: 数据库 Skills 集合 - 监控、诊断、安全、调度、SQL执行
Home-page: https://github.com/magicCzc/dbskiter.git
Author: MagiCzc
Author-email: MagiCzc <magiczc@139.com>
License: MIT
Project-URL: Homepage, https://github.com/magicCzc/dbskiter
Project-URL: Repository, https://github.com/magicCzc/dbskiter.git
Project-URL: Issues, https://github.com/magicCzc/dbskiter/issues
Keywords: database,mysql,oracle,postgresql,clickhouse,sqlite,dba,aiops
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: pymysql>=1.0.0
Requires-Dist: psycopg2-binary>=2.9.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: requests>=2.28.0
Requires-Dist: jinja2>=3.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: sqlparse>=0.5.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Provides-Extra: oracle
Requires-Dist: oracledb>=1.4.0; extra == "oracle"
Requires-Dist: JayDeBeApi>=1.2.0; extra == "oracle"
Provides-Extra: report
Requires-Dist: weasyprint>=59.0; extra == "report"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# dbskiter - 数据库AIOps运维助手

<p align="center">
  <strong>开源免费的数据库运维工具，让AI帮你管理数据库</strong>
</p>

<p align="center">
  <a href="#快速开始">快速开始</a> |
  <a href="#功能特性">功能特性</a> |
  <a href="#使用示例">使用示例</a> |
  <a href="#项目架构">项目架构</a> |
  <a href="#ai集成">AI集成</a>
</p>

---

## 项目简介

**dbskiter** 是一个开源的数据库运维工具集，提供诊断、监控、安全审计、SQL执行等核心功能。

### 适用场景

- 中小企业没有专职DBA
- 需要快速诊断数据库问题
- 定期安全审计和巡检
- AI辅助的数据库管理

### 支持数据库

| 级别 | 数据库 | 说明 |
|------|--------|------|
| 深度支持 | MySQL / MariaDB | 专用驱动，功能最完善，含AAS计算、慢查询分析 |
| 深度支持 | Oracle | 专用驱动，11g/12c/19c+，含性能分析器 |
| 深度支持 | PostgreSQL | 专用驱动，诊断、监控、锁分析全覆盖 |
| 深度支持 | SQL Server (MSSQL) | 专用驱动，2016+，支持 Query Store |
| 深度支持 | ClickHouse | 专用驱动，诊断、监控、锁分析全覆盖 |
| 深度支持 | SQLite | 专用驱动，诊断、监控全覆盖 |
| 通用支持 | Trino / Presto | Generic 驱动，通过 INFORMATION_SCHEMA 适配 |
| 通用支持 | DuckDB | Generic 驱动，基础诊断与监控 |
| 通用支持 | Apache Derby, H2, HSQLDB | Generic 驱动，基础诊断与监控 |
| 理论支持 | 任何 JDBC 4.0+ 兼容数据库 | Generic 驱动自动能力探测适配 |

**架构说明**: 本项目采用 **"6 + N" 双层驱动架构**。6 个专用驱动覆盖主流数据库的深度功能，Generic 驱动为其余 JDBC 兼容数据库提供基础支持。Generic 驱动通过运行时能力探测自动适配（检测 INFORMATION_SCHEMA、pg_stat_activity、v$session 等系统视图的存在情况），不支持的功能优雅降级返回提示而非报错。

---

## 快速开始

### 1. 安装

```bash
# 克隆仓库
git clone https://github.com/magicCzc/dbskiter.git
cd dbskiter

# 安装依赖
pip install -e .
```

### 2. 配置环境变量

创建 `.env` 文件（**切勿提交到Git仓库**）：

```bash
# 复制示例配置
cp .env.example .env

# 编辑 .env 文件，填入你的数据库配置
```

**最小配置示例（单数据库）**：

```bash
# MySQL配置
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=your_database
```

**多实例配置示例（推荐）**：

```bash
# MySQL - 示例库1（示例配置，请替换为实际值）
DB_JUMP_HOST=your_mysql_host
DB_JUMP_PORT=3306
DB_JUMP_USER=your_username
DB_JUMP_PASSWORD=your_password
DB_JUMP_NAME=your_database
DB_JUMP_DIALECT=mysql+pymysql

# MySQL - 示例库2（示例配置，请替换为实际值）
DB_CHENZC_HOST=your_mysql_host
DB_CHENZC_PORT=3306
DB_CHENZC_USER=your_username
DB_CHENZC_PASSWORD=your_password
DB_CHENZC_NAME=your_database
DB_CHENZC_DIALECT=mysql+pymysql

# Oracle - 示例库（示例配置，请替换为实际值）
DB_ORCL_HOST=your_oracle_host
DB_ORCL_PORT=1521
DB_ORCL_USER=your_username
DB_ORCL_PASSWORD=your_password
DB_ORCL_SERVICE=orcl
DB_ORCL_DIALECT=oracle+jdbc

# SQL Server - 示例库（示例配置，请替换为实际值）
DB_MSSQL_HOST=your_sqlserver_host
DB_MSSQL_PORT=1433
DB_MSSQL_USER=your_username
DB_MSSQL_PASSWORD=your_password
DB_MSSQL_NAME=your_database
DB_MSSQL_DIALECT=mssql+pyodbc
```

**使用别名连接**：

```bash
# 使用别名连接指定数据库
dbskiter --database=jump sql execute "SELECT 1"
dbskiter --database=orcl sql execute "SELECT 1 FROM DUAL"
dbskiter --database=mssql sql execute "SELECT 1"
```

### 3. 验证安装

```bash
# 查看帮助
dbskiter --help

# 测试连接（使用默认配置或指定数据库）
dbskiter monitor health
dbskiter --database=jump monitor health
```

---

## 功能特性

### 1. 数据库诊断 (db-diagnose)

SQL诊断、慢查询分析、索引推荐、性能报告。

```bash
# 诊断慢查询
dbskiter --database=<数据库名> diagnose slow-queries --limit=10

# 诊断特定SQL
dbskiter --database=<数据库名> diagnose sql "SELECT * FROM users WHERE email='test@example.com'"

# 推荐索引
dbskiter --database=<数据库名> diagnose recommend-indexes --table=orders

# 生成综合报告
dbskiter --database=<数据库名> diagnose report
```

### 2. 健康监控 (db-monitor)

健康检查、异常检测、容量预测、趋势分析。

```bash
# 健康检查
dbskiter --database=<数据库名> monitor health

# 异常检测
dbskiter --database=<数据库名> monitor anomalies

# 容量预测（磁盘）
dbskiter --database=<数据库名> monitor capacity --resource=disk --days=30

# 查看历史趋势
dbskiter --database=<数据库名> monitor history cpu_usage
```

### 3. 安全审计 (db-security)

SQL注入检测、敏感数据扫描、权限审计、密码策略检查。

```bash
# 完整安全审计
dbskiter --database=<数据库名> security audit

# SQL注入检测
dbskiter --database=<数据库名> security sql-injection "SELECT * FROM users WHERE id=%s"

# 敏感数据扫描
dbskiter --database=<数据库名> security sensitive-data

# 检查密码策略
dbskiter --database=<数据库名> security password-policy
```

### 4. SQL执行 (sql-master)

智能SQL执行、数据导入导出、SQL审核。

```bash
# 执行SQL
dbskiter --database=<数据库名> sql execute "SELECT COUNT(*) FROM users"

# 导出数据
dbskiter --database=<数据库名> sql export --table=users --output=users.csv

# SQL审核
dbskiter --database=<数据库名> sql audit "SELECT * FROM orders"
```

### 5. 锁分析 (db-lock-analyzer)

锁分析、死锁检测、锁等待链追踪。

```bash
# 分析当前锁
dbskiter --database=<数据库名> lock analyze

# 检测死锁
dbskiter --database=<数据库名> lock deadlocks

# 查看锁等待链
dbskiter --database=<数据库名> lock chains
```

### 6. 智能巡检 (db-inspector)

配置检查、性能检查、安全检查、根因分析。

```bash
# 执行巡检
dbskiter --database=<数据库名> inspector run

# 生成报告
dbskiter --database=<数据库名> inspector report --output=report.html

# 智能巡检
dbskiter --database=<数据库名> inspector intelligent
```

---

## 使用示例

### 场景1：数据库变慢了

```bash
# 1. 快速健康检查
dbskiter --database=<数据库名> monitor health

# 2. 查看慢查询
dbskiter --database=<数据库名> diagnose slow-queries --limit=5

# 3. 分析锁情况
dbskiter --database=<数据库名> lock analyze

# 4. 获取优化建议
dbskiter --database=<数据库名> diagnose recommend-indexes
```

### 场景2：日常安全巡检

```bash
# 1. 安全审计
dbskiter --database=<数据库名> security audit

# 2. 检查弱密码
dbskiter --database=<数据库名> security weak-passwords

# 3. 扫描敏感数据
dbskiter --database=<数据库名> security sensitive-data

# 4. 生成巡检报告
dbskiter --database=<数据库名> inspector report
```

### 场景3：容量规划

```bash
# 1. 磁盘容量预测
dbskiter --database=<数据库名> monitor capacity --resource=disk --days=90

# 2. 连接数趋势
dbskiter --database=<数据库名> monitor trend --metric=connections

# 3. 查看历史数据
dbskiter --database=<数据库名> monitor history table_size
```

---

## 项目架构

```
dbskiter/
├── __main__.py                   # Python模块入口
├── cli.py                        # CLI桥接入口
├── mcp_integration.py            # MCP协议集成
│
├── config/                       # 配置模块
│   └── security_config.py       # 安全配置
│
├── cli/                          # CLI命令入口
│   ├── commands/                 # 各模块命令实现
│   │   ├── diagnose.py          # 诊断命令
│   │   ├── diagnose_report_generator.py # 诊断报告生成命令
│   │   ├── monitor.py           # 监控命令
│   │   ├── security.py          # 安全命令
│   │   ├── sql.py               # SQL命令
│   │   ├── lock.py              # 锁分析命令
│   │   ├── inspector.py         # 巡检命令
│   │   ├── scheduler.py         # 调度命令
│   │   └── audit.py             # 审核命令
│   ├── main.py                  # CLI主入口
│   ├── config.py                # 配置管理
│   ├── config_file.py           # 配置文件解析
│   ├── readonly_middleware.py   # 只读安全中间件
│   ├── error_handler.py        # CLI错误处理
│   ├── exceptions.py           # CLI异常定义
│   └── output.py               # 输出格式化
│
├── db_diagnose/                  # 诊断模块
│   ├── skill.py                 # 诊断Skill主类
│   ├── diagnosticians/          # 各数据库诊断器
│   │   ├── base.py             # 诊断器基类
│   │   ├── generic_diagnostician.py # 通用诊断器
│   │   ├── mysql_diagnostician.py
│   │   ├── mysql_performance_analyzer.py # MySQL性能分析
│   │   ├── postgresql_diagnostician.py
│   │   ├── postgresql_performance_analyzer.py # PG性能分析
│   │   ├── oracle_diagnostician.py
│   │   ├── oracle_performance_analyzer.py # Oracle性能分析
│   │   ├── oracle_slow_query_analyzer.py # Oracle慢查询分析
│   │   ├── clickhouse_diagnostician.py
│   │   ├── clickhouse_performance_analyzer.py # CH性能分析
│   │   ├── mssql_diagnostician.py
│   │   ├── sqlite_diagnostician.py
│   │   └── sqlite_performance_analyzer.py # SQLite性能分析
│   ├── analyzers/               # 各类分析器
│   │   ├── sql_analyzer.py
│   │   ├── plan_analyzer.py
│   │   ├── table_analyzer.py
│   │   └── batch_analyzer.py
│   ├── core/                    # 核心组件
│   │   ├── performance_model.py
│   │   └── slow_query_analyzer.py
│   ├── reports/                 # 报告生成
│   │   └── generator.py
│   ├── models.py                # 数据模型
│   └── utils.py                 # 工具函数
│
├── db_monitor/                   # 监控模块
│   ├── skill.py                 # 监控Skill主类
│   ├── collectors/              # 指标采集器
│   │   ├── base.py             # 采集器基类
│   │   ├── generic_collector.py # 通用采集器
│   │   ├── mysql_collector.py
│   │   ├── postgresql_collector.py
│   │   ├── oracle_collector.py
│   │   ├── clickhouse_collector.py
│   │   ├── mssql_collector.py
│   │   └── sqlite_collector.py
│   ├── storage.py               # 数据存储
│   ├── health_scorer.py         # 健康评分
│   ├── capacity_predictor.py    # 容量预测
│   ├── advanced_predictor.py    # 高级预测
│   ├── trend_analyzer.py        # 趋势分析
│   ├── models.py                # 数据模型
│   └── utils.py                 # 工具函数
│
├── db_security/                  # 安全模块
│   ├── skill.py                 # 安全Skill主类
│   ├── sql_injection_detector_v2.py  # SQL注入检测
│   ├── sensitive_data_scanner_v2.py  # 敏感数据扫描
│   ├── password_policy_checker.py    # 密码策略检查
│   ├── advanced_security_analyzer.py # 高级安全分析
│   ├── audit_log_analyzer.py    # 审计日志分析
│   ├── login_security_monitor.py # 登录安全监控
│   ├── models.py                # 数据模型
│   └── utils.py                 # 工具函数
│
├── db_scheduler/                 # 调度模块
│   ├── skill.py                 # 调度Skill主类
│   ├── backup.py                # 备份管理
│   ├── connection_pool.py       # 连接池管理
│   ├── scheduler_engine.py      # 调度引擎
│   ├── task_executors.py        # 任务执行器
│   ├── task_storage.py          # 任务持久化
│   ├── persistent_storage.py    # 通用持久化
│   ├── models.py                # 数据模型
│   ├── utils.py                 # 工具函数
│   ├── dependency_manager.py    # 依赖管理
│   ├── distributed_lock.py      # 分布式锁
│   ├── monitoring.py            # 监控
│   └── result_cleanup.py        # 结果清理
│
├── db_inspector/                 # 巡检模块
│   ├── skill.py                 # 巡检Skill主类
│   ├── intelligent_inspector.py # 智能巡检
│   ├── inspectors/              # 各数据库巡检器
│   │   ├── base.py             # 巡检器基类
│   │   ├── generic_inspector.py # 通用巡检器
│   │   ├── mysql_inspector.py
│   │   ├── postgresql_inspector.py
│   │   ├── oracle_inspector.py
│   │   ├── clickhouse_inspector.py
│   │   ├── mssql_inspector.py
│   │   └── sqlite_inspector.py
│   ├── report_generator.py      # 报告生成
│   ├── models.py                # 数据模型
│   └── utils.py                 # 工具函数
│
├── db_lock_analyzer/             # 锁分析模块
│   ├── skill.py                 # 锁分析Skill主类
│   ├── models.py                # 数据模型
│   └── utils.py                 # 工具函数
│
├── sql_master/                   # SQL执行模块
│   ├── skill.py                 # SQL Skill主类
│   ├── executor.py              # SQL执行器
│   ├── security_checker.py      # SQL安全检查器
│   ├── security_executor_v2.py  # 安全执行器
│   ├── sql_parser.py            # SQL解析器
│   ├── sql_rewriter_v2.py       # SQL重写器
│   ├── analyzer.py              # SQL分析器
│   ├── data_transfer.py         # 数据传输
│   ├── audit_storage.py         # 审计存储
│   ├── audit_logger.py          # 审计日志
│   ├── cache_manager.py         # 缓存管理
│   ├── cache_invalidator.py     # 缓存失效
│   ├── schema_aware.py          # Schema感知
│   ├── intelligent_intellisense.py  # 智能提示
│   ├── models.py                # 数据模型
│   └── utils.py                 # 工具函数
│
├── db_sql_auditor/               # SQL审核模块
│   ├── skill.py                 # 审核Skill主类
│   ├── analyzers/               # 各数据库审核器
│   │   ├── base.py             # 审核器基类
│   │   ├── generic_analyzer.py # 通用审核器
│   │   ├── mysql_analyzer.py
│   │   ├── postgresql_analyzer.py
│   │   ├── oracle_analyzer.py
│   │   ├── clickhouse_analyzer.py
│   │   ├── mssql_analyzer.py
│   │   └── sqlite_analyzer.py
│   ├── intelligent_optimizer.py # 智能优化器
│   ├── models.py                # 数据模型
│   └── utils.py                 # 工具函数
│
└── shared/                       # 共享组件
    ├── database_connector.py    # 数据库连接器（可配置连接池）
    ├── unified_connector.py     # 统一连接器（JDBC/SQLAlchemy适配器）
    ├── sql_utils.py             # SQL工具函数共享（表名提取/类型检测/能力摘要等）
    ├── query_result.py          # 查询结果模型
    ├── validators.py            # 输入验证和脱敏
    ├── error_handler.py         # 统一异常处理
    ├── models.py                # 共享数据模型
    ├── db_metadata.py           # 数据库元数据
    ├── schema_detector.py       # 数据库类型检测
    ├── sql_dialect.py           # SQL方言适配
    ├── sql_fingerprint.py       # SQL指纹计算
    ├── utils.py                 # 通用工具函数
    ├── ai_context.py            # AI上下文
    ├── zabbix_client.py         # Zabbix监控客户端
    ├── prometheus_client.py     # Prometheus指标采集
    ├── prometheus_metrics.py    # Prometheus指标定义
    ├── oracle_jdbc_connector.py # Oracle JDBC连接器
    ├── oracle_metrics.py        # Oracle指标定义
    ├── slow_log_parser.py       # 慢日志解析
    ├── mysql_slow_query_collector.py # MySQL慢查询采集
    └── mysql_aas_calculator_v2.py    # AAS计算
```

---

## AI集成

dbskiter 支持多种AI集成方式，包括MCP Server和Skill文档。

### MCP Server（推荐）

通过Model Context Protocol与Claude、Cursor等AI助手集成。

**安装MCP Server：**
```bash
pip install dbskiter-mcp-server
```

**配置Claude Desktop：**
编辑 `claude_desktop_config.json`：
```json
{
  "mcpServers": {
    "dbskiter": {
      "command": "dbskiter-mcp",
      "env": {
        "DB_DIALECT": "mysql",
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_USER": "root",
        "DB_PASSWORD": "your_password",
        "DB_NAME": "your_database"
      }
    }
  }
}
```

**使用示例：**
用户可以直接问Claude：
- "检查我的数据库健康状态"
- "分析这个SQL语句的性能"
- "找出最慢的10个查询"

### Skill文档

通过Skill文档让AI IDE（如Trae、Cursor）学会使用工具。

**配置方法：**
```bash
# Trae IDE
cp -r .trae/skills/* ~/.trae/skills/

# Cursor IDE
cp -r .trae/skills/* .cursor/skills/
```

**AI使用示例：**

**用户**：帮我检查数据库健康状态

**AI**（自动读取 Skill 文档）：
```bash
# 执行健康检查
dbskiter --database=<数据库名> monitor health --json

# 解析结果
健康评分：85/100
状态：健康
连接数：45/100 (45%)
CPU使用率：35%
建议：系统运行良好，无需处理
```

### 相关项目

- [dbskiter-mcp-server](https://github.com/magicCzc/dbskiter-mcp-server) - MCP Server实现

---

## 高级配置

### 多数据库配置

```bash
# 使用别名连接指定数据库（推荐方式）
dbskiter --database=jump monitor health
dbskiter --database=orcl monitor health

# 或使用前缀方式（向后兼容）
dbskiter --prefix=ORACLE monitor health
dbskiter --prefix=MYSQL2 monitor health
```

### JSON输出

```bash
# 便于程序解析
dbskiter --database=<数据库名> --json monitor health
```

### 详细日志

```bash
# 查看 Generic 驱动能力探测结果等 INFO 级别日志
dbskiter --database=trino --verbose diagnose realtime

# --verbose 会显示 Generic 驱动自动探测到的能力摘要：
# [Generic驱动] 能力探测: 版本查询, 可用视图: INFORMATION_SCHEMA
```

### 调试模式

### 配合Prometheus

```bash
# 导出Prometheus格式指标
dbskiter --database=<数据库名> monitor collect
```

---

## 重要说明

### 安全设计

dbskiter 采用三层纵深防御架构保障数据安全:

| 层级 | 机制 | 说明 |
|------|------|------|
| AI层 | 规则限制 | AI助手禁止执行写操作SQL |
| CLI层 | ReadOnlyEnforcer | 环境变量控制, 拦截写操作 |
| 数据库层 | 用户权限 | 数据库账号权限物理限制 |

关键安全措施:

- **密码保护**: MySQL使用MYSQL_PWD环境变量传递密码, PostgreSQL使用PGPASSWORD环境变量, 避免密码在进程列表中暴露
- **SQL注入防护**: 表名白名单正则验证, 值转义覆盖反斜杠和单引号, 恢复操作仅允许白名单语句类型(INSERT/CREATE TABLE/DROP TABLE IF EXISTS等)
- **条件解析安全**: 告警条件表达式使用自定义解析器, 不使用eval(), 仅支持比较运算和逻辑运算
- **只读模式**: 恢复操作在只读模式下被拒绝, 防止误操作
- **表名引号包裹**: 根据数据库类型自动选择引号(MySQL/ClickHouse用反引号, PostgreSQL用双引号), 支持schema.table限定表名

```bash
# 启用只读模式
export DBSKITER_READ_ONLY=true
dbskiter --database=mydb diagnose realtime
```

### 定位说明

dbskiter 是**诊断工具**，不是实时监控系统。

| 场景 | 推荐方案 |
|------|----------|
| 实时监控 | Prometheus + Grafana |
| 告警通知 | Alertmanager |
| 故障诊断 | **dbskiter** |
| SQL优化 | **dbskiter** |
| 安全审计 | **dbskiter** |

### 连接池配置

通过环境变量自定义连接池参数（无需修改代码）：

```bash
# 连接池大小（默认5）
DB_POOL_SIZE=10
# 最大溢出连接（默认10）
DB_POOL_MAX_OVERFLOW=20
# 连接超时秒数（默认30）
DB_POOL_TIMEOUT=60
# 连接回收周期秒数（默认3600，即1小时）
DB_POOL_RECYCLE=7200
```

也可以在代码中通过 kwargs 传入：

```python
conn = DatabaseConnector(
    dialect="mysql",
    host="localhost",
    database="mydb",
    username="user",
    password="pass",
    pool_size=10,
    pool_max_overflow=20
)
```

### 定时任务示例

```bash
# 每小时健康检查（使用默认配置）
0 * * * * dbskiter monitor health --json > /var/log/db-health.json

# 每天安全审计（指定数据库）
0 2 * * * dbskiter --database=jump security audit > /var/log/db-security-audit.log
```

---

## 文档

- [CLI使用指南](CLI使用指南.md)
- [AI集成指南](AI集成指南.md)
- [Skill系统介绍](.trae/skills/README.md)

---

## 开发

```bash
# 安装开发依赖
pip install -e ".[dev]"

# 代码格式化
black dbskiter/

# 类型检查
mypy dbskiter/
```

---

## License

MIT License

---

<p align="center">
  <strong>让每个人都能轻松管理数据库</strong>
</p>
