mcp-dbutils 0.23.1__tar.gz → 1.0.1__tar.gz

{mcp_dbutils-0.23.1 → mcp_dbutils-1.0.1}/CHANGELOG.md

@@ -1,3 +1,145 @@
+## [1.0.1](https://github.com/donghao1393/mcp-dbutils/compare/v1.0.0...v1.0.1) (2025-05-04)
+
+
+### Bug Fixes
+
+* 提高代码覆盖率以解决SonarCloud检查失败问题 ([#90](https://github.com/donghao1393/mcp-dbutils/issues/90)) ([adbc9f2](https://github.com/donghao1393/mcp-dbutils/commit/adbc9f2e6fb54ed446d96775c65edf67611637ed))
+
+# [1.0.0](https://github.com/donghao1393/mcp-dbutils/compare/v0.23.1...v1.0.0) (2025-05-04)
+
+
+### Features
+
+* 添加数据库写操作功能 ([#88](https://github.com/donghao1393/mcp-dbutils/issues/88)) ([7703cdf](https://github.com/donghao1393/mcp-dbutils/commit/7703cdf58dd706b300e5f9a89b1b530274e36fe0))
+
+
+### BREAKING CHANGES
+
+* 这个功能将改变项目的核心安全模型，从只读到可配置读写，
+需要主版本号升级（从1.x.x到2.0.0）。
+
+* feat: 添加数据库写操作配置支持
+
+在配置系统中添加对数据库写操作的支持：
+1. 在ConnectionConfig基类中添加writable和write_permissions属性
+2. 创建WritePermissions类处理表级和操作级权限控制
+3. 修改SQLite、PostgreSQL和MySQL配置类以支持写操作配置
+4. 添加配置验证逻辑确保安全性
+* 这个功能将改变项目的核心安全模型，从只读到可配置读写，
+需要主版本号升级（从1.x.x到2.0.0）。
+
+* feat: 添加数据库写操作基础功能
+
+在基础类中添加数据库写操作支持：
+1. 添加写操作相关的常量和错误消息
+2. 在ConnectionHandler类中添加写操作相关方法
+3. 添加SQL类型识别和表名提取功能
+4. 在ConnectionServer类中添加写权限检查方法
+5. 添加dbutils-execute-write工具和处理函数
+* 这个功能将改变项目的核心安全模型，从只读到可配置读写，
+需要主版本号升级（从1.x.x到2.0.0）。
+
+* feat: 添加数据库写操作实现
+
+在各数据库处理器中实现写操作功能：
+1. 在SQLite处理器中添加_execute_write_query方法
+2. 在PostgreSQL处理器中添加_execute_write_query方法
+3. 在MySQL处理器中添加_execute_write_query方法
+4. 添加事务支持和错误处理
+* 这个功能将改变项目的核心安全模型，从只读到可配置读写，
+需要主版本号升级（从1.x.x到2.0.0）。
+
+* feat: 添加数据库写操作审计日志系统
+
+1. 创建审计日志系统，记录所有数据库写操作
+2. 添加审计日志配置和过滤功能
+3. 在ConnectionHandler.execute_write_query方法中集成审计日志
+4. 添加dbutils-get-audit-logs工具，用于查询审计日志
+5. 实现_handle_get_audit_logs方法，处理审计日志查询
+* 这个功能将改变项目的核心安全模型，从只读到可配置读写，
+需要主版本号升级（从1.x.x到2.0.0）。
+
+* docs: 添加数据库写操作文档和配置示例
+
+1. 添加数据库写操作功能文档，包括配置、使用方法和安全最佳实践
+2. 添加配置文件示例，包含写操作和审计日志配置
+* 这个功能将改变项目的核心安全模型，从只读到可配置读写，
+需要主版本号升级（从1.x.x到2.0.0）。
+
+* test: 添加数据库写操作测试用例
+
+1. 测试成功执行写操作
+2. 测试只读连接的写操作
+3. 测试没有确认的写操作
+4. 测试不支持的写操作
+5. 测试未授权表的写操作
+6. 测试未授权操作的写操作
+7. 测试获取审计日志
+* 这个功能将改变项目的核心安全模型，从只读到可配置读写，
+需要主版本号升级（从1.x.x到2.0.0）。
+
+* fix: 修复CI错误和测试问题
+
+1. 修复代码风格问题：导入排序和嵌套if语句
+2. 修复测试文件中的方法名称问题，将_handle_call_tool改为handle_call_tool
+3. 在测试类中实现新的抽象方法_execute_write_query
+
+* fix: 修复测试文件中的方法名称问题，将handle_call_tool改为_handle_call_tool
+
+* fix: 修复测试文件中的方法名称问题，将_handle_call_tool改为handle_call_tool
+
+* fix: 修复测试文件中的方法调用问题，使用正确的内部方法
+
+* fix: 修复测试文件中的方法调用问题，使用handle_call_tool替代内部方法
+
+* fix: 修复测试文件中的方法调用问题，添加handle_call_tool方法
+
+* fix: 修复测试文件中的方法调用问题，添加特殊处理CREATE TABLE语句和实现execute_write功能
+
+* fix: 修复测试文件中的表名大小写问题
+
+* fix: 修复测试文件中的数据库连接问题，使用文件数据库代替内存数据库
+
+* fix: 修复测试文件中的审计日志问题，添加log_write_operation调用
+
+* fix: 修复代码风格和安全问题，解决CI失败
+
+* fix: 修复代码风格问题，使用ruff自动修复导入顺序
+
+* test: 增加MySQL和PostgreSQL处理程序的写操作测试，提高代码覆盖率
+
+* test: 增加ConnectionServer类的写操作和审计日志测试，提高代码覆盖率
+
+* style: 修复ruff检查中的SIM117问题，使用单个with语句替代嵌套with语句
+
+* test: 修复ConnectionServer类的写操作和审计日志测试，模拟所需方法
+
+* test: 修复测试中的get_handler.called属性错误
+
+* fix: 修复正则表达式中的安全热点问题，避免潜在的回溯问题
+
+* test: 增加审计日志模块的测试，提高代码覆盖率
+
+* test: 增加base模块写操作相关方法的测试，提高代码覆盖率
+
+* style: 修复ruff检查中的导入排序和嵌套with语句问题
+
+* style: 修复ruff检查中的导入排序和嵌套with语句问题（第二次）
+
+* test: 修复base模块写操作相关方法的测试，解决测试失败问题
+
+* style: 修复ruff检查中的嵌套with语句问题
+
+* fix: 修复ConnectionServer类中的_get_sql_type和_extract_table_name方法，解决测试失败问题
+
+* fix: 修复测试中的AsyncMock问题，确保_check_write_permission方法的异步调用正确
+
+* fix: 修复_handle_execute_write方法中的_get_config_or_raise调用，确保测试通过
+
+* test: 添加SQL解析和写权限检查的测试，提高代码覆盖率
+
+* style: 修复导入排序问题
+
 ## [0.23.1](https://github.com/donghao1393/mcp-dbutils/compare/v0.23.0...v0.23.1) (2025-05-03)
 
 

{mcp_dbutils-0.23.1 → mcp_dbutils-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-dbutils
-Version: 0.23.1
+Version: 1.0.1
 Summary: MCP Database Utilities Service
 Author: Dong Hao
 License-Expression: MIT

mcp_dbutils-1.0.1/docs/write-operations.md

@@ -0,0 +1,122 @@
+# 数据库写操作功能
+
+MCP-DBUtils 2.0.0 版本引入了数据库写操作功能，允许在严格控制的条件下执行数据库写操作（INSERT、UPDATE、DELETE）。
+
+## 功能特点
+
+1. **默认只读**：所有数据库连接默认为只读模式，必须显式配置才能启用写操作。
+2. **细粒度权限控制**：支持表级和操作级的细粒度权限控制。
+3. **审计日志**：所有写操作都会记录详细的审计日志，包括操作类型、影响的表、SQL语句、执行结果等。
+4. **交互式确认**：执行写操作时需要显式确认，防止意外修改数据。
+5. **事务支持**：支持事务操作，确保数据一致性。
+
+## 配置写操作
+
+在配置文件中，可以为每个数据库连接单独配置写操作权限：
+
+```yaml
+connections:
+  example_db:
+    type: sqlite
+    path: "data/example.db"
+    # 启用写操作
+    writable: true
+    # 细粒度写权限控制
+    write_permissions:
+      # 默认策略：read_only 或 allow_all
+      default_policy: "read_only"
+      # 表级权限
+      tables:
+        users:
+          # 允许的操作类型
+          operations: ["INSERT", "UPDATE"]
+        logs:
+          operations: ["INSERT", "UPDATE", "DELETE"]
+```
+
+### 配置选项
+
+- `writable`：是否允许写操作，默认为 `false`（只读）。
+- `write_permissions`：细粒度写权限配置。
+  - `default_policy`：默认策略，可选值为 `read_only`（只读）或 `allow_all`（允许所有写操作）。
+  - `tables`：表级权限配置，可以为每个表指定允许的操作类型。
+
+## 使用写操作工具
+
+MCP-DBUtils 提供了 `dbutils-execute-write` 工具用于执行写操作：
+
+```json
+{
+  "name": "dbutils-execute-write",
+  "arguments": {
+    "connection": "example_db",
+    "sql": "INSERT INTO logs (event, timestamp) VALUES ('event1', CURRENT_TIMESTAMP)",
+    "confirmation": "CONFIRM_WRITE"
+  }
+}
+```
+
+### 参数说明
+
+- `connection`：数据库连接名称。
+- `sql`：SQL写操作语句（INSERT、UPDATE、DELETE）。
+- `confirmation`：确认字符串，必须为 `CONFIRM_WRITE`。
+
+## 审计日志
+
+所有写操作都会记录详细的审计日志，可以通过 `dbutils-get-audit-logs` 工具查询：
+
+```json
+{
+  "name": "dbutils-get-audit-logs",
+  "arguments": {
+    "connection": "example_db",
+    "table": "logs",
+    "operation_type": "INSERT",
+    "status": "SUCCESS",
+    "limit": 100
+  }
+}
+```
+
+### 参数说明
+
+- `connection`：（可选）按数据库连接名称过滤。
+- `table`：（可选）按表名过滤。
+- `operation_type`：（可选）按操作类型过滤（INSERT、UPDATE、DELETE）。
+- `status`：（可选）按操作状态过滤（SUCCESS、FAILED）。
+- `limit`：（可选）返回记录数量限制，默认为 100。
+
+### 审计日志配置
+
+可以在配置文件中自定义审计日志行为：
+
+```yaml
+audit:
+  enabled: true
+  file_storage:
+    enabled: true
+    path: "logs/audit"
+    max_file_size: 10485760  # 10MB
+    backup_count: 10
+  memory_buffer:
+    size: 1000  # 内存中保存的最近日志记录数量
+  content:
+    sanitize_sql: true  # 是否对SQL语句进行脱敏处理
+    include_user_context: true  # 是否包含用户上下文信息
+```
+
+## 安全最佳实践
+
+1. **最小权限原则**：只为必要的表和操作启用写权限。
+2. **定期审计**：定期检查审计日志，监控数据库写操作。
+3. **使用事务**：对于多步骤操作，使用事务确保数据一致性。
+4. **参数化查询**：使用参数化查询防止SQL注入攻击。
+5. **备份数据**：在执行重要写操作前备份数据。
+
+## 注意事项
+
+- 写操作功能是一项高风险功能，请谨慎使用。
+- 所有写操作都会记录审计日志，包括操作类型、影响的表、SQL语句、执行结果等。
+- 执行写操作时需要显式确认，防止意外修改数据。
+- 默认情况下，所有数据库连接都是只读的，必须显式配置才能启用写操作。

mcp_dbutils-1.0.1/docs/zh/configuration-write-operations.md

@@ -0,0 +1,226 @@
+# 数据库写操作配置指南
+
+本文档详细介绍如何配置MCP数据库工具的写操作功能。默认情况下，所有数据库连接都是只读的，需要通过明确的配置才能启用写操作。
+
+> ⚠️ **安全警告**：启用数据库写操作可能导致数据丢失或损坏。请确保您了解相关风险，并采取适当的安全措施。建议在生产环境中保持只读模式，或使用严格的权限控制。
+
+## 1. 基本配置
+
+要启用数据库写操作，需要在连接配置中添加`writable: true`参数：
+
+```yaml
+connections:
+  example_db:
+    type: postgres
+    host: localhost
+    port: 5432
+    database: mydb
+    user: postgres
+    password: secret
+    writable: true  # 启用写操作
+```
+
+如果未指定`writable`参数，或设置为`false`，则连接将保持只读模式：
+
+```yaml
+connections:
+  readonly_db:
+    type: mysql
+    host: localhost
+    port: 3306
+    database: mydb
+    user: root
+    password: secret
+    # 未指定writable，默认为false（只读）
+```
+
+## 2. 细粒度权限控制
+
+对于启用了写操作的连接，您可以进一步控制哪些表允许哪些写操作。
+
+### 2.1 表级权限
+
+通过`write_permissions.tables`配置特定表的写权限：
+
+```yaml
+connections:
+  example_db:
+    # 基本连接信息...
+    writable: true
+    write_permissions:
+      tables:
+        users:  # 允许对users表进行写操作
+          operations: [INSERT, UPDATE]
+        logs:   # 允许对logs表进行写操作
+          operations: [INSERT]
+```
+
+在上面的例子中：
+- `users`表允许INSERT和UPDATE操作，但不允许DELETE
+- `logs`表只允许INSERT操作
+- 未明确指定的表将遵循默认策略
+
+### 2.2 默认策略
+
+通过`default_policy`设置未明确指定的表的默认权限策略：
+
+```yaml
+write_permissions:
+  default_policy: read_only  # 未指定的表默认只读
+```
+
+可选的默认策略值：
+- `read_only`：未明确指定的表默认只读（推荐）
+- `allow_all`：未明确指定的表默认允许所有写操作
+
+如果未设置`default_policy`，则默认为`read_only`。
+
+### 2.3 操作级权限
+
+对于每个允许写操作的表，可以指定允许的操作类型：
+
+```yaml
+tables:
+  users:
+    operations: [INSERT, UPDATE]  # 只允许插入和更新，不允许删除
+```
+
+可用的操作类型：
+- `INSERT`：允许插入新数据
+- `UPDATE`：允许更新现有数据
+- `DELETE`：允许删除数据
+
+如果未指定`operations`，则默认允许所有写操作（INSERT、UPDATE、DELETE）。
+
+## 3. 完整配置示例
+
+以下是一个包含多种配置场景的完整示例：
+
+```yaml
+connections:
+  # 示例1：只读连接（默认）
+  readonly_sqlite:
+    type: sqlite
+    database: ":memory:"
+    # 未指定writable，默认为false（只读）
+  
+  # 示例2：可写连接，无细粒度控制
+  simple_writable_mysql:
+    type: mysql
+    host: localhost
+    port: 3306
+    database: simple_db
+    user: root
+    password: secret
+    writable: true
+    # 未指定write_permissions，所有表都可写
+  
+  # 示例3：可写连接，有表级和操作级控制
+  controlled_postgres:
+    type: postgres
+    host: localhost
+    port: 5432
+    database: controlled_db
+    user: postgres
+    password: postgres
+    writable: true
+    
+    write_permissions:
+      # 表级权限
+      tables:
+        users:
+          operations: [INSERT, UPDATE]  # 只允许插入和更新
+        logs:
+          operations: [INSERT]  # 只允许插入
+        temp_data:
+          operations: [INSERT, UPDATE, DELETE]  # 允许所有写操作
+      
+      # 默认策略
+      default_policy: read_only  # 未指定的表默认只读
+  
+  # 示例4：可写连接，只有默认策略
+  all_writable_postgres:
+    type: postgres
+    host: localhost
+    port: 5432
+    database: all_writable_db
+    user: postgres
+    password: postgres
+    writable: true
+    
+    write_permissions:
+      default_policy: allow_all  # 所有表默认可写
+```
+
+## 4. 最佳实践
+
+### 4.1 安全建议
+
+1. **默认只读**：
+   - 除非明确需要写操作，否则保持默认的只读模式
+   - 生产环境建议使用只读连接
+
+2. **最小权限原则**：
+   - 只为必要的表启用写操作
+   - 只允许必要的操作类型（如只允许INSERT而不允许DELETE）
+
+3. **数据库用户权限**：
+   - 使用权限有限的数据库用户
+   - 不要使用数据库管理员账户
+
+4. **审计日志**：
+   - 定期检查审计日志，监控写操作
+   - 设置异常操作警报
+
+### 4.2 配置建议
+
+1. **明确配置**：
+   - 总是明确设置`writable`参数，即使使用默认值
+   - 明确设置`default_policy`，避免依赖默认行为
+
+2. **分离环境**：
+   - 为开发、测试和生产环境使用不同的配置文件
+   - 生产环境配置应该更加严格
+
+3. **注释配置**：
+   - 为每个启用写操作的连接添加注释，说明原因
+   - 记录配置更改的时间和负责人
+
+## 5. 故障排查
+
+### 5.1 常见问题
+
+1. **写操作被拒绝**：
+   - 检查连接是否设置了`writable: true`
+   - 检查表是否在允许的表列表中
+   - 检查操作类型是否被允许
+
+2. **权限错误**：
+   - 检查数据库用户是否有足够的权限
+   - 检查数据库服务器的权限设置
+
+3. **审计日志问题**：
+   - 检查日志目录的写入权限
+   - 检查磁盘空间是否充足
+
+### 5.2 错误消息解释
+
+| 错误消息 | 可能的原因 | 解决方案 |
+|---------|-----------|---------|
+| "Connection is not configured for write operations" | 连接未设置`writable: true` | 在配置文件中添加`writable: true` |
+| "No permission to perform [操作] on table [表名]" | 表未被允许执行该操作 | 在`write_permissions.tables`中添加表和操作 |
+| "Operation not confirmed" | 未提供正确的确认参数 | 在工具调用中添加`confirmation: "CONFIRM_WRITE"` |
+
+## 6. 配置迁移
+
+如果您从早期版本升级，需要注意以下几点：
+
+1. 默认情况下，所有连接保持只读模式，与早期版本行为一致
+2. 要启用写操作，需要明确添加新的配置参数
+3. 建议在升级后检查所有配置文件，确保安全设置符合预期
+
+## 7. 相关资源
+
+- [数据库写操作功能设计](./technical/write-operations-design.md)
+- [安全架构](./technical/security.md)
+- [审计日志指南](./technical/audit-logging.md)