smart-query

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Smart Query - 智能问数

Smart Query - Intelligent Data Query

通过 SSH 隧道安全连接线上数据库，支持自然语言查询和 SQL 执行。

Securely connect to online databases via SSH tunnel, supporting natural language queries and SQL execution.

触发场景

Trigger Scenarios

用户问"查一下xxx数据"、"帮我看看xxx表"
用户需要查询线上数据库
用户问"有哪些表"、"表结构是什么"

When users ask "Check xxx data", "Help me view the xxx table"
When users need to query online databases
When users ask "What tables are there", "What is the table structure"

快速使用

Quick Start

1. 测试连接

1. Test Connection

bash

python .opencode/skills/smart-query/scripts/db_connector.py

bash

python .opencode/skills/smart-query/scripts/db_connector.py

2. 执行SQL查询

2. Execute SQL Query

bash

python .opencode/skills/smart-query/scripts/query.py "SELECT * FROM table_name LIMIT 10"
python .opencode/skills/smart-query/scripts/query.py "SHOW TABLES"
python .opencode/skills/smart-query/scripts/query.py "DESC table_name"

参数：

```
-n 50
```
：限制返回行数
```
-f json
```
：JSON格式输出
```
--raw
```
：输出原始结果（含元信息）

bash

python .opencode/skills/smart-query/scripts/query.py "SELECT * FROM table_name LIMIT 10"
python .opencode/skills/smart-query/scripts/query.py "SHOW TABLES"
python .opencode/skills/smart-query/scripts/query.py "DESC table_name"

Parameters:

```
-n 50
```
: Limit the number of returned rows
```
-f json
```
: Output in JSON format
```
--raw
```
: Output raw results (including metadata)

3. 生成表结构文档

3. Generate Table Structure Documentation

bash

python .opencode/skills/smart-query/scripts/schema_loader.py

生成

references/schema.md

，包含所有表结构信息。

bash

python .opencode/skills/smart-query/scripts/schema_loader.py

Generates

references/schema.md

, which contains all table structure information.

自然语言查询流程

Natural Language Query Process

理解用户意图：分析用户想查什么数据
查阅表结构：读取
```
references/schema.md
```
了解表结构
生成SQL：根据表结构编写正确的SQL
执行查询：使用
```
query.py
```
执行
解读结果：用通俗语言解释查询结果

Understand User Intent: Analyze what data the user wants to query
Check Table Structure: Read
```
references/schema.md
```
to understand the table structure
Generate SQL: Write correct SQL based on the table structure
Execute Query: Execute using
```
query.py
```
Interpret Results: Explain query results in plain language

配置说明

Configuration Instructions

配置文件：

config/settings.json

json

{
  "ssh": {
    "host": "SSH跳板机地址",
    "port": 22,
    "username": "用户名",
    "password": "密码",
    "key_file": null
  },
  "database": {
    "type": "mysql",
    "host": "数据库内网地址",
    "port": 3306,
    "database": "库名",
    "username": "数据库用户",
    "password": "数据库密码"
  }
}

Configuration File:

config/settings.json

json

{
  "ssh": {
    "host": "SSH bastion host address",
    "port": 22,
    "username": "Username",
    "password": "Password",
    "key_file": null
  },
  "database": {
    "type": "mysql",
    "host": "Database intranet address",
    "port": 3306,
    "database": "Database name",
    "username": "Database user",
    "password": "Database password"
  }
}

分享给同事

Share with Colleagues

复制整个
```
smart-query/
```
目录

同事复制

config/settings.json.example

为

settings.json

填入自己的 SSH 和数据库连接信息
安装依赖：
```
pip install paramiko sshtunnel pymysql
```

Copy the entire
```
smart-query/
```
directory

Colleagues copy

config/settings.json.example

settings.json

Fill in their own SSH and database connection information
Install dependencies:
```
pip install paramiko sshtunnel pymysql
```

安全提示

Security Tips

```
config/settings.json
```
包含敏感信息，不要提交到 Git
建议将
```
config/settings.json
```
加入
```
.gitignore
```
只执行 SELECT 查询，避免 UPDATE/DELETE 操作

```
config/settings.json
```
contains sensitive information, do not commit it to Git
It is recommended to add
```
config/settings.json
```
to
```
.gitignore
```
Only execute SELECT queries, avoid UPDATE/DELETE operations

依赖安装

Dependency Installation

bash

pip install paramiko sshtunnel pymysql

bash

pip install paramiko sshtunnel pymysql

脚本清单

Script List

脚本	用途
`scripts/db_connector.py`	SSH隧道+数据库连接，可单独运行测试连接
`scripts/query.py`	执行SQL查询，支持表格/JSON输出
`scripts/schema_loader.py`	加载表结构，生成 schema.md

Script	Purpose
`scripts/db_connector.py`	SSH tunnel + database connection, can be run independently to test the connection
`scripts/query.py`	Execute SQL queries, support table/JSON output
`scripts/schema_loader.py`	Load table structure, generate schema.md

参考文档

Reference Documents

文档	说明
`references/schema.md`	数据库表结构（运行 schema_loader.py 生成）

Document	Description
`references/schema.md`	Database table structure (generated by running schema_loader.py)