feat(tools): add chDB tools for in-process ClickHouse SQL#6533
Open
ShawnChen-Sirius wants to merge 3 commits into
Open
feat(tools): add chDB tools for in-process ClickHouse SQL#6533ShawnChen-Sirius wants to merge 3 commits into
ShawnChen-Sirius wants to merge 3 commits into
Conversation
Seven tools over chdb.agents.ChDBTool, the agent-tool surface the chdb package ships: run_select_query (read-only ClickHouse SQL with parameter binding), list_databases, list_tables, describe_table, get_sample_data, list_functions, and attach_file, plus a chdb_tools() factory that builds the suite over one shared engine so attached tables are visible across tools. The engine runs inside the Python process, so unlike server-backed SQL tools there is no connection string, credential, or env var. Safety is engine-level rather than prompt-level: sessions default to the ClickHouse readonly=2 setting, results are capped by max_rows/max_bytes with a truncated flag, and every call returns a JSON envelope (ok/result or ok/error) so the agent can read engine errors and self-correct instead of crashing the run. chdb is an optional dependency (crewai-tools[chdb]): importing crewai_tools works without it, and tools raise a descriptive ImportError at first use. Unit tests run against a mocked engine; integration tests skip when chdb is not installed. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
chdb 4.2.1 is the minimum for the new crewai-tools chdb extra and was released 2026-07-13, inside the rolling 3-day exclude-newer window; add it to the per-package overrides so resolution succeeds, following the existing entries. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughAdds an optional chDB dependency and a CrewAI tool suite for queries, introspection, file attachments, shared engine lifecycle, JSON responses, and read-only enforcement. Public exports, documentation, package configuration, unit tests, and integration tests are included. ChangesChDB Tool Suite
Sequence Diagram(s)sequenceDiagram
participant Agent
participant ChDBRunSelectQueryTool
participant ChDBTool
participant ChDBEngine
Agent->>ChDBRunSelectQueryTool: submit SQL and params
ChDBRunSelectQueryTool->>ChDBTool: dispatch run_select_query
ChDBTool->>ChDBEngine: call or acall
ChDBEngine-->>ChDBTool: JSON success or error envelope
ChDBTool-->>Agent: return serialized response
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@lib/crewai-tools/src/crewai_tools/tools/chdb_tool/chdb_tool.py`:
- Around line 11-20: Update ChDBBaseTool.close in
lib/crewai-tools/src/crewai_tools/tools/chdb_tool/chdb_tool.py:11-20 to close
the underlying session or guard the cleanup so it does not unconditionally call
the unsupported ChDBTool.close method. The references in
lib/crewai-tools/pyproject.toml:151-154 and pyproject.toml:175-176 require no
direct changes.
In `@lib/crewai-tools/tests/tools/chdb_tool_test.py`:
- Around line 169-171: Scope the chdb dependency skip to only the real-engine
integration tests, not the mocked unit tests in chdb_tool_test.py. Move those
integration tests and the pytest.importorskip("chdb") call into a separate test
module, or apply per-test/class-level skipping to the integration-test symbols
while keeping the mocked tests runnable without chdb.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 484a1f90-3612-4e88-b17f-964e8d233d72
📒 Files selected for processing (8)
lib/crewai-tools/pyproject.tomllib/crewai-tools/src/crewai_tools/__init__.pylib/crewai-tools/src/crewai_tools/tools/__init__.pylib/crewai-tools/src/crewai_tools/tools/chdb_tool/README.mdlib/crewai-tools/src/crewai_tools/tools/chdb_tool/__init__.pylib/crewai-tools/src/crewai_tools/tools/chdb_tool/chdb_tool.pylib/crewai-tools/tests/tools/chdb_tool_test.pypyproject.toml
A module-level pytest.importorskip skips the entire file, so the mocked unit tests were skipped along with the integration tests on machines without chdb. Guard the integration tests individually with a skipif marker instead: without chdb the 13 unit tests still run (6 integration tests skip); with chdb all 19 run. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Seven tools that give agents analytical SQL over local and remote data with chDB, the in-process ClickHouse engine, wrapping
chdb.agents.ChDBTool(the agent-tool surface thechdbpackage ships and conformance-tests):ChDBRunSelectQueryTool(run_select_query) — read-only ClickHouse SQL with{name:Type}parameter bindingChDBListDatabasesTool,ChDBListTablesTool,ChDBDescribeTableTool,ChDBGetSampleDataTool,ChDBListFunctionsTool— schema discovery, including describing table-function expressions likes3('…','Parquet')ChDBAttachFileTool(attach_file) — register a local file as a named table (writable sessions only)chdb_tools()— builds the suite over one shared engine, so a table one tool attaches is visible to the othersWhy (vs existing SQL tools)
readonly=2(INSERT/CREATE/ALTER/DROP rejected by the engine while SELECT andfile()/s3()/url()keep working — same direction as the NL2SQLTool read-only hardening);max_rows/max_bytescap every payload with an explicittruncatedflag; optionalfile_allowlistconfines file-like sources to listed prefixes and refuses DSN-based sources.{"ok": true, "result": …}/{"ok": false, "error": {code, type, message}}), so a wrong query becomes feedback the agent corrects instead of an exception that kills the crew run.Notes for reviewers
chdbis an optional dependency (crewai-tools[chdb]).import crewai_toolsworks without it; tools raise a descriptive ImportError at first use.exclude-newerwindow, so the second commit adds it to the existingexclude-newer-packageoverrides. From 2026-07-16 the entry is no longer needed and can be dropped whenever convenient.uv.lockis intentionally untouched (CI re-resolves; happy to include the regenerated lock if you prefer).tool.specs.jsonis intentionally untouched — the Generate Tool Specifications workflow doesn't run for fork PRs; happy to include the regenerated file instead._arundelegates to the engine'sacall()rather than blocking the loop.ChDBBaseToolis importable from the subpackage but not exported at the top level, mirroringDaytonaBaseTool.run_select_query, …); they can be renamed at construction if a crew combines multiple SQL suites.Testing
tests/tools/chdb_tool_test.py: unit tests against a mocked engine (no chdb needed) plus integration tests (pytest.importorskip("chdb")) covering parameter binding, the readonly=2 write rejection envelope, attach-then-query engine sharing, read-only attachments, and the introspection tools.ruff check/ruff formatand strictmypy(repo config, pydantic plugin) clean.import crewai_toolssucceeds and tools construct with chdb absent (import blocked via a meta-path hook), with the lazy ImportError pointing atcrewai-tools[chdb].