boxed-dev/cognidb

# CogniDB 3.0 **为应用程序提供安全的自然语言 SQL** —— 这是一个 Python **库**，而不是聊天产品。 **状态：** Git / 源代码发布版本 **3.0.1** 已可从此仓库安装。在维护者上传之前，PyPI 可能仍会显示旧的历史版本 —— 请参阅 [docs/RELEASE-CHECKLIST.md](docs/RELEASE-CHECKLIST.md)。在 PyPI 上出现 `cognidb==3.0.0` 之前，建议通过克隆仓库使用 `pip install -e .` 进行安装。 默认：**读取模式**（仅限 SELECT）→ 验证 → 可选的表/列白名单 → 执行 → 审计。 可选开启：**写入模式**（INSERT/UPDATE/DELETE）、schema 关联、单次修复尝试、**intent 模式**（`generation_mode="intent"`）。 ## 安装 ``` # 从源码安装（在 PyPI 3.0.1 发布之前推荐） python -m venv .venv && source .venv/bin/activate pip install -e ".[dev]" # 可选附加组件（参见 pyproject.toml） # pip install -e ".[redis]" # Redis 缓存 # pip install -e ".[mongo]" # Mongo 驱动实验 ``` ``` pytest -q ``` ## 快速开始（离线 SQLite，30 行以内） 无需网络 LLM —— 使用内置预设 SQL 的 `FakeSQLGenerator`： ``` from cognidb.drivers import SQLiteDriver from cognidb.pipeline import SecureQueryPipeline from cognidb.security import QuerySecurityValidator, InputSanitizer, StatementPolicy, StatementMode from cognidb.ai.fake_generator import FakeSQLGenerator drv = SQLiteDriver({"database": ":memory:"}) drv.connect() drv.execute_native_query("CREATE TABLE users (id INTEGER, name TEXT)") drv.execute_native_query("INSERT INTO users VALUES (1, 'Ada')") pipe = SecureQueryPipeline( driver=drv, generator=FakeSQLGenerator("SELECT id, name FROM users"), validator=QuerySecurityValidator(), sanitizer=InputSanitizer(), schema=drv.fetch_schema(), policy=StatementPolicy(mode=StatementMode.READ), enable_audit=False, ) print(pipe.run("list users").to_dict()) drv.disconnect() ``` 相同脚本：`python examples/sqlite_offline_demo.py`。 ## 高级客户端（需要数据库 + LLM 凭据） ``` from cognidb import CogniDB, create_cognidb # 环境变量：DB_* 和 LLM_API_KEY，或者传入配置 / cognidb.yaml with CogniDB(config_file="cognidb.yaml") as db: result = db.query("Show the top 10 customers by revenue", explain=True) if result["success"]: print(result["sql"], result["results"]) ``` `examples/basic_usage.py` 演示了高级 API，但**需要有效的数据库和 LLM API 密钥** —— 它并非离线运行。 ## 3.0 版本包含的内容 | 功能 | 备注 | |---|---| | 方言 | SQLite、PostgreSQL、MySQL | | `SecureQueryPipeline` | 单一的自然语言到 SQL（NL→SQL）再到执行路径 | | 语句策略 | 默认为读取；可选开启写入；始终拒绝 DDL | | 白名单 | 启用后提供表 + 列的访问控制 | | Intent 模式 | 可选开启的结构化 `QueryIntent` → 确定性的 SQL 渲染 | | 离线测试 | `FakeSQLGenerator` / `FakeIntentGenerator` | | LLM 提供商 | OpenAI、Anthropic、Azure OpenAI；HuggingFace/本地使用需要额外依赖 | | 文档 | [SECURITY.md](SECURITY.md), [docs/threat-model.md](docs/threat-model.md), [CHANGELOG.md](CHANGELOG.md), [ROADMAP.md](ROADMAP.md) | ## 安全性（简述） - 通过驱动程序进行参数化执行；对生成的 SQL 应用验证器 + 清理器 - 可选的 `AccessController` 用于表/列白名单（当列受限时，遇到 `SELECT *` 将拒绝执行） - 审计日志钩子；对抗性语料库位于 `tests/security/corpus/` 下 ``` from cognidb.security import AccessController access = AccessController() access.create_restricted_user( user_id="analyst_1", table_permissions_dict={ "customers": { "operations": ["SELECT"], "columns": ["id", "name", "email", "country"], "row_filter": "country = 'USA'", } }, ) # 将 access_controller 传入 SecureQueryPipeline 并设置 enable_access_control=True # 或通过 CogniDB settings / yaml 进行配置。 ``` ## 配置 环境变量（`DB_TYPE`、`DB_HOST`、`DB_NAME`、`DB_USER`、`DB_PASSWORD`、`LLM_PROVIDER`、`LLM_API_KEY`、……）或 YAML —— 请参阅 `cognidb.example.yaml`。 ## 开发 ``` git clone https://github.com/boxed-dev/cognidb cd cognidb python -m venv .venv && source .venv/bin/activate pip install -e ".[dev]" pytest ``` 贡献指南：[CONTRIBUTING.md](CONTRIBUTING.md)。行为准则：[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)。 发布步骤（人工 + PyPI token）：[docs/RELEASE-CHECKLIST.md](docs/RELEASE-CHECKLIST.md)。 ## 许可证 MIT —— 请参阅 [LICENSE](LICENSE)。

标签：NL2SQL, Python, 搜索引擎查询, 数据库工具, 无后门, 测试用例, 逆向工具