chdb-sql Skill for Claude: Run ClickHouse SQL on Files and Databases in Python

Makes Claude run ClickHouse SQL on local files, S3 and remote databases from Python, without setting up a server.

Installs: 9.3K; on skills.sh
Stars: 565; on GitHub
Files: 7; besides SKILL.md
Updated: Oct 2026; last repo commit

This skill is published by ClickHouse in its own agent-skills repo. It makes Claude use chDB, the embedded ClickHouse engine for Python, to run SQL on local files, URLs, S3 paths and remote sources such as Postgres, MySQL, MongoDB, ClickHouse Cloud, Iceberg and Delta Lake. It covers one-off chdb.query() calls, stateful Sessions, DB-API connections and parametrized queries.

It needs Python 3.9+ on macOS or Linux and pip install chdb. It bundles a small verify_install.py check. For pandas-style DataFrame code it points to a different skill, chdb-datastore. Examples put database passwords inside the SQL text, so use read-only credentials.

Good for

Analysts who want SQL on parquet, CSV or JSON files without loading a database
Engineers joining files with MySQL, Postgres, S3 or data lake tables in one query
Python users who import chdb or want ClickHouse SQL functions

Install chdb-sql

Claude Code

Copy this prompt.

Install the chdb-sql skill in Claude Code. Run this command:

pip install chdb

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Python 3.9+.

Pick one skill route. The README installs the whole repo with npx skills add clickhouse/agent-skills; the command here names only chdb-sql. The plugin route installs the 8 skills listed in plugin.json (counted there), including chdb-sql; the repo tree has no hook or MCP config files. The skill needs Python 3.9+ on macOS or Linux; check the setup with python scripts/verify_install.py from the skill folder.

From the project README. Source.

What's in the skill

When it loads

Use when the user wants to run SQL — especially analytical SQL — on local files (parquet/csv/json), URLs, S3 paths, or remote databases (Postgres, MySQL, MongoDB, ClickHouse Cloud, Iceberg, Delta Lake) without setting up a server. Provides chDB — embedded ClickHouse SQL in Python with 1000+ functions, Session for stateful multi-step pipelines, parametrized queries, and cross-source joins via `s3()`, `mysql()`, `postgresql()`, `iceberg()`, `deltaLake()`, `remoteSecure()` table functions. TRIGGER when: user wants SQL on parquet/csv/files or across remote analytical sources; uses ClickHouse SQL features (window functions, windowFunnel, geoToH3, JSON path ops, Session, parametrized queries); imports `chdb` or calls `chdb.query()`. SKIP this skill for pandas-style DataFrame method-chaining (use chdb-datastore instead) or ClickHouse server administration.

Sections in SKILL.md

Decision Tree: Pick the Right API
chdb.query() — One Line, Any Data
Session — Stateful Analysis Pipelines
Connection API (DB-API 2.0)
Troubleshooting
References

Key facts

Author: ClickHouse Inc (metadata.json; the frontmatter names chdb-io)
Repo: clickhouse/agent-skills
Installs on skills.sh: 9,263 (Nov 2, 2026)
GitHub stars: 565 (Nov 2, 2026, whole repo)
License: Apache-2.0 (SKILL.md)
Last repo commit: Oct 30, 2026
What installs: 8 files including SKILL.md: README, examples, metadata.json, 3 reference notes and scripts/verify_install.py
Skill version: 4.1 (frontmatter); 4.1.0 in metadata.json
Needs: Python 3.9+, macOS or Linux, and pip install chdb
skills.sh audits: Gen Agent Trust Hub pass, Socket pass, Snyk warn (Nov 2, 2026)

What it includes

One-off SQL on files, URLs, S3, databases and data lakes, with output formats
Table functions include file(), s3(), mysql(), postgresql(), iceberg(), deltaLake() and remoteSecure(). Output can be a DataFrame, and queries accept {name:Type} parameters.
Runs code · chdb.query()
Stateful analysis: tables, joins and multi-step pipelines, in memory or in a local folder
chs.Session("./analytics_db") keeps data on disk; Session() keeps it in memory. The example copies remote tables into local MergeTree tables.
Runs code · Session
DB-API 2.0 connection with cursor.execute and fetchall
For code that expects a standard database interface.
Runs code · chdb.connect() / dbapi
Checks Python version, chdb import, a query, DataFrame output, a Session and parameters
Run it from the skill directory. The Session check creates a temporary Memory table named _verify_test.
Runs code · scripts/verify_install.py
API reference, table functions, SQL functions and 9 runnable examples
Files: references/api-reference.md, table-functions.md, sql-functions.md and examples/examples.md.
References and examples
Fixes for missing chdb, file not found, unknown table function, remote connection refused
For example, deltaLake is spelled with a capital L.
Troubleshooting table

From the official docs

Permissions

Medium risk

It runs Python and SQL against files and remote databases using credentials that appear in the query text. Use read-only database users and keep passwords out of shared chats.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

Database passwords sit inside the SQL
The examples call mysql('db:3306', 'shop', 'orders', 'root', 'pass') with the user and password as arguments, so they show up in the code and the chat. Use a read-only user. github.com
It installs a Python package and runs Python
SKILL.md has you run pip install chdb, and the queries run in your Python process. A Session with a folder path writes a local database there. github.com
Queries reach any remote source you name
S3, URLs and databases in a query are contacted from your machine. The skill names no fixed hosts. github.com

Technical details

Sign-in and keys	Database user and password are passed as arguments inside the SQL in the examples, so they appear in the code and the chat.
Scopes	Runs pip install chdb and Python code that queries your files, URLs, S3 paths and databases A Session with a folder path writes a local database there Can run scripts/verify_install.py, which runs a test query and creates a temporary table

Questions

What does the chdb-sql skill do?

It makes Claude run ClickHouse SQL inside Python with chDB. You can query parquet, CSV and JSON files, URLs, S3 and remote databases, and join across sources, without running a server.

How do I install it in Claude Code?

Use the install box at the top. You also need chdb in Python: pip install chdb, on Python 3.9+ with macOS or Linux.

Does it need an API key?

No key is named. Queries against private databases or buckets need whatever credentials those systems use, and the examples pass them inside the SQL.

chdb-sql or chdb-datastore?

Use chdb-sql for SQL. SKILL.md says to use chdb-datastore for pandas-style DataFrame method chaining, and the repo marketplace lists it separately.

Is it made by ClickHouse?

Yes. It sits in the clickhouse/agent-skills repo, and metadata.json names ClickHouse Inc. The SKILL.md frontmatter lists chdb-io as author.

Does it work in the Claude app?

The README does not document the Claude app. The skill runs Python with chdb on your machine, so use a client that can run commands.

Is it safe?

It bundles one Python check script and reference notes. The risk is in what Claude runs: pip install chdb, SQL against your files and any remote database you name, and passwords written into queries. Use read-only credentials and review queries first.

Information

updated Nov 2, 2026

Repository: clickhouse/agent-skills
Folder: skills/chdb-sql

clickhouse/agent-skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 7

SKILL.md · github.com
agent-skills README · github.com
verify_install.py · github.com
chdb-sql README · github.com
marketplace.json · github.com
metadata.json · github.com
examples.md · github.com