QueryClaw

# QueryClaw

**Your Database, Under AI Command.**

> [中文版](README_CN.md)

[![PyPI](https://img.shields.io/pypi/v/queryclaw)](https://pypi.org/project/queryclaw/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10+-blue)](https://python.org)

<!-- TODO: Add demo to docs/assets/demo.gif (asciinema or GIF), then uncomment:
![Demo](docs/assets/demo.gif)
-->

**7 tools** | **7 skills** | **4 databases** | **243+ tests** | **Multi-LLM via LiteLLM**

---

## What is QueryClaw?

**QueryClaw** is an AI-native database agent that lets you hand over an entire database instance to an LLM-powered Agent. Think of it as giving your database a brain — it can explore schemas, query data, modify records, diagnose performance, and even generate new data using AI, all through natural language.

**This is not another Text-to-SQL chatbot.** QueryClaw is a full [ReACT](https://arxiv.org/abs/2210.03629) Agent that reasons, acts, observes, and iterates — it works the way a developer thinks about data, but with the depth of a seasoned DBA.

### The Idea

[OpenClaw](https://github.com/openclaw/openclaw) proved that an LLM can safely control a personal computer. **QueryClaw asks: what if we give it a database instead?**

| | OpenClaw / nanobot | QueryClaw |
|---|---|---|
| **Controls** | Operating System | Database |
| **Interface** | Shell, filesystem, browser | SQL, schema, data |
| **Safety** | Sandboxed execution | Transaction rollback, dry-run, audit |
| **Audience** | General users | Application developers & DBAs |

## Why QueryClaw?

Developers spend countless hours on repetitive database tasks: writing queries, debugging data issues, generating test data, reviewing schema designs, analyzing performance. Most database tools are either too low-level (raw SQL clients) or too limited (drag-and-drop query builders).

QueryClaw sits in the sweet spot: **an intelligent agent that understands both your natural language intent and the database semantics**.

### Before / After

| | Traditional Workflow | With QueryClaw |
|---|---|---|
| **Query** | Write SQL by hand, guess table names | `"Show me top customers"` — Agent explores schema and builds the query |
| **Modify data** | Write UPDATE, hope WHERE is correct, no audit | Agent validates, dry-runs, asks for confirmation, records before/after snapshot |
| **Generate test data** | Write scripts, handle FK constraints manually | `"Generate 100 test users with orders"` — respects schema automatically |
| **Diagnose slow query** | Run EXPLAIN, read docs, iterate | `"Why is this query slow?"` — Agent runs EXPLAIN, suggests indexes |
| **Team collaboration** | Share SQL snippets in chat | Ask in Feishu/DingTalk, Agent replies with results directly |

### Key Differentiators

- **Autonomous reasoning** — A full ReACT agent loop, not a one-shot translator. It explores schemas, runs queries, observes results, and adjusts its approach across multiple steps
- **Safety-first writes** — Multi-layer protection for mutations: policy checks → SQL AST validation → dry-run → human confirmation → transaction wrapping → full audit with before/after snapshots
- **Multi-channel** — Use it in the terminal (`queryclaw chat`) or deploy to team messaging (`queryclaw serve`) for Feishu / DingTalk with interactive confirmation
- **Extensible skills** — Add new capabilities via `SKILL.md` markdown files — no code changes, no redeployment. The agent loads skills on demand
- **Multi-database** — MySQL, PostgreSQL, SQLite, SeekDB (OceanBase) with a clean adapter interface for adding more

### What You Can Do

```
> "Show me the top 10 customers by revenue last quarter"
> "Why is this query slow? Suggest indexes"
> "Generate 100 realistic test users with orders"
> "Find orphaned records and fix foreign key violations"
> "Based on product descriptions, generate a one-sentence summary column"
> "What tables are related to the orders system? Draw the relationships"
```

## Installation

```bash
pip install queryclaw
```

For PostgreSQL support:

```bash
pip install queryclaw[postgresql]
```

For Feishu channel support:

```bash
pip install queryclaw[feishu]
```

For DingTalk channel support:

```bash
pip install queryclaw[dingtalk]
```

For all optional features (PostgreSQL + SQL validation + Feishu + DingTalk):

```bash
pip install queryclaw[all]
```

## Quick Start

```bash
# 1. Initialize configuration
queryclaw onboard

# 2. Edit config — set your database connection and LLM API key
#    Config location: ~/.queryclaw/config.json

# 3. Start chatting with your database
queryclaw chat
```

Example interaction:

```
You: What tables are in this database?
Agent: [calls schema_inspect] Found 12 tables. Here are the main ones...

You: Show me the top 5 customers by total order amount
Agent: [calls query_execute] Here are the results...

You: Add an index on orders.customer_id
Agent: ⚠️ This is a DDL operation. Proceed? [y/N]
```

For channel mo

... (truncated)