Skip to content

Commit beb25ac

Browse files
jaguarliuujaguarliuu
authored
Merge pull request #94 from jaguarliuu/dev/jagaurliu
feat:修改 readme 文档
2 parents 885366d + c3349ea commit beb25ac

File tree

2 files changed

+116
-52
lines changed

2 files changed

+116
-52
lines changed

‎README.md‎

Lines changed: 55 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
**Type:** tool
66

77
### Description
8-
A tool that converts natural language into secure and optimized SQL queries, supporting both MySQL and PostgreSQL databases.
8+
A tool that converts natural language into secure and optimized SQL queries, supporting multiple mainstream databases including MySQL, PostgreSQL, Oracle, SQL Server, and Chinese domestic databases (GaussDB, KingbaseES, DM).
99

1010

1111
### 声明
@@ -17,17 +17,26 @@ We are truly grateful for the overwhelming interest in this experimental project
1717
### ✨ Core Features
1818

1919
#### ​Multi-Database Support
20-
- Native support for MySQL and PostgreSQL syntax differences
20+
- Native support for 7 database types with automatic syntax adaptation
21+
- International databases: MySQL, PostgreSQL, Oracle, SQL Server
22+
- Chinese domestic databases: GaussDB (Huawei), KingbaseES (KINGBASE), DM (Dameng)
2123
- Automatic SQL syntax adaptation based on database type (e.g., LIMIT vs FETCH FIRST)
24+
- Schema-aware query generation for databases that support schemas
25+
2226
#### ​Security Mechanisms
23-
- Mandatory result set limits (default LIMIT 100)
27+
- Mandatory result set limits (default LIMIT 100, configurable up to 100,000)
2428
- DML operation prohibition (SELECT statements only)
2529
- Field whitelist validation (based on database metadata)
2630
- Least privilege principle for query execution
2731

2832
### Supported Databases
29-
MySQL
30-
PostgreSQL
33+
- **MySQL** - Full support with optimized query generation
34+
- **PostgreSQL** - Native support with schema awareness
35+
- **Oracle** - Enterprise database with schema support
36+
- **SQL Server** - Microsoft SQL Server support
37+
- **GaussDB** - Huawei's enterprise-grade database (openGauss compatible)
38+
- **KingbaseES** - Kingbase's PostgreSQL-compatible database
39+
- **DM (Dameng)** - Dameng's Oracle-compatible database
3140

3241
### Supported LLMs
3342
Compatible with ​all non-deep-thinking models
@@ -41,35 +50,56 @@ Compatible with ​all non-deep-thinking models
4150
1. Import the rookie_text2data plugin
4251
2. Configure basic parameters:
4352

44-
| Parameter | Type | Required | Description | Multilingual Support |
45-
|----------------|----------------|----------|---------------------------------------------------|--------------------------|
46-
| db_type | select | Yes | Database type (MySQL/PostgreSQL) | CN/EN/PT |
47-
| host | string | Yes | Database host/IP address | CN/EN/PT |
48-
| port | number | Yes | Database port (1-65535) | CN/EN/PT |
49-
| db_name | string | Yes | Target database name | CN/EN/PT |
50-
| table_name | string | No | Comma-separated table names (empty for all tables)| CN (format hints) |
51-
| username | string | Yes | Database username | CN/EN/PT |
52-
| password | secret-input | Yes | Database password | CN/EN/PT |
53-
| model | model-selector | Yes | LLM model configuration | CN/EN/PT |
54-
| query | string | Yes | Natural language query statement | CN/EN/PT |
55-
56-
3. Select Model，We recommend using the Qwen-max model. Other models can be tested but deep-thinking models are unsupported.
53+
| Parameter | Type | Required | Description | Multilingual Support |
54+
|----------------|----------------|----------|----------------------------------------------------------------|--------------------------|
55+
| db_type | select | Yes | Database type (MySQL/PostgreSQL/Oracle/SQL Server/GaussDB/KingbaseES/DM) | CN/EN/PT |
56+
| host | string | Yes | Database host/IP address | CN/EN/PT |
57+
| port | number | Yes | Database port (1-65535) | CN/EN/PT |
58+
| db_name | string | Yes | Target database name | CN/EN/PT |
59+
| table_names | string | No | Comma-separated table names (empty for all tables) | CN (format hints) |
60+
| schema_name | string | No | Schema name (PostgreSQL default: public, Oracle/DM: uppercase username) | CN/EN/PT |
61+
| username | string | Yes | Database username | CN/EN/PT |
62+
| password | secret-input | Yes | Database password | CN/EN/PT |
63+
| model | model-selector | Yes | LLM model configuration | CN/EN/PT |
64+
| query | string | Yes | Natural language query statement | CN/EN/PT |
65+
| limit | number | No | Query result limit (1-100000, default 100) | CN/EN/PT |
66+
| result_format | select | No | Result format (JSON/TEXT, default JSON) | CN/EN/PT |
67+
| custom_prompt | string | No | Custom prompt for fine-tuning query generation | CN/EN/PT |
68+
| with_comment | boolean | No | Include database comments in schema metadata | CN/EN/PT |
69+
70+
3. Select Model - We recommend using the Qwen-max model. Other models can be tested but deep-thinking models are unsupported.
5771
4. Generate SQL queries using natural language
5872

5973
#### SQL Execution Component
6074
1. Import the rookie_execute_sql plugin
6175
2. Configure basic parameters:
6276

63-
| Parameter | Type | Required | Description | Multilingual Support |
64-
|---------------|----------|----------|------------------------------------------|--------------------------|
65-
| db_type | select | Yes | Database type (MySQL/PostgreSQL) | CN/EN/PT |
66-
| host | string | Yes | Database host/IP address | CN/EN/PT |
67-
| port | number | Yes | Database port (1-65535) | CN/EN/PT |
68-
| db_name | string | Yes | Target database name | CN/EN/PT |
69-
| sql | string | Yes | SQL query to execute | CN/EN/PT |
77+
| Parameter | Type | Required | Description | Multilingual Support |
78+
|----------------|--------------|----------|----------------------------------------------------------------|--------------------------|
79+
| db_type | select | Yes | Database type (MySQL/PostgreSQL/Oracle/SQL Server/GaussDB/KingbaseES/DM) | CN/EN/PT |
80+
| host | string | Yes | Database host/IP address | CN/EN/PT |
81+
| port | number | Yes | Database port (1-65535) | CN/EN/PT |
82+
| db_name | string | Yes | Target database name | CN/EN/PT |
83+
| username | string | Yes | Database username | CN/EN/PT |
84+
| password | secret-input | Yes | Database password | CN/EN/PT |
85+
| schema | string | No | Schema name (PostgreSQL default: public, Oracle/DM: uppercase username) | CN/EN/PT |
86+
| sql | string | Yes | SQL query to execute | CN/EN/PT |
87+
| result_format | select | No | Result format (JSON/TEXT/CSV, default JSON) | CN/EN/PT |
7088

7189
3. Click "Execute" to run the SQL statement
7290

91+
### Database-Specific Notes
92+
93+
#### Chinese Domestic Databases
94+
- **GaussDB**: Compatible with PostgreSQL protocol, uses SCRAM-SHA-256 authentication
95+
- **KingbaseES**: PostgreSQL-compatible, supports schema-based organization
96+
- **DM (Dameng)**: Oracle-compatible, uses Oracle-style schema management
97+
98+
#### Schema Configuration
99+
- **PostgreSQL/GaussDB/KingbaseES**: Default schema is `public`, can be customized
100+
- **Oracle/DM**: Default schema is the uppercase version of your username (e.g., user `admin` → schema `ADMIN`)
101+
- **MySQL/SQL Server**: Schema parameter not required
102+
73103
### License
74104

75105
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

‎README_ZH.md‎

Lines changed: 61 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
## rookie_text2data
22

33
**Author:** jaguarliuu
4-
**Version:** 0.3.1
4+
**Version:** 1.0.1
55
**Type:** tool
66

77
### Description
8-
将自然语言转换为安全、优化的 SQL 查询工具，支持 MySQL 和 PostgreSQL 数据库。
8+
将自然语言转换为安全、优化的 SQL 查询工具，支持多种主流数据库，包括 MySQL、PostgreSQL、Oracle、SQL Server 以及国产数据库（高斯、人大金仓、达梦）。
99

1010

1111
### 声明
@@ -21,19 +21,26 @@
2121
### ✨ 核心特性
2222

2323
#### ​**多数据库支持**
24-
- 原生支持 MySQL 和 PostgreSQL 语法差异
24+
- 原生支持 7 种数据库类型，自动语法适配
25+
- 国际主流数据库：MySQL、PostgreSQL、Oracle、SQL Server
26+
- 国产数据库：GaussDB（华为高斯）、KingbaseES（人大金仓）、DM（达梦）
2527
- 自动识别数据库类型生成适配的 SQL 语法（如 `LIMIT` vs `FETCH FIRST`）
28+
- 支持 Schema 感知的查询生成
2629

2730
#### ​**安全防护**
28-
- 强制结果集限制（默认 `LIMIT 100`）
31+
- 强制结果集限制（默认 `LIMIT 100`，可配置至 100,000）
2932
- 禁止 DML 操作（仅允许 SELECT 语句）
3033
- 字段白名单验证（基于数据库元数据）
3134
- 使用最小权限原则执行查询
3235

33-
3436
### 数据库支持
35-
- MySQL
36-
- PostgreSQL
37+
- **MySQL** - 完整支持，优化查询生成
38+
- **PostgreSQL** - 原生支持，Schema 感知
39+
- **Oracle** - 企业级数据库，支持 Schema
40+
- **SQL Server** - 微软 SQL Server 支持
41+
- **GaussDB** - 华为企业级数据库（兼容 openGauss）
42+
- **KingbaseES** - 人大金仓数据库（兼容 PostgreSQL）
43+
- **DM（达梦）** - 达梦数据库（兼容 Oracle）
3744

3845
### 大模型支持
3946

@@ -49,32 +56,59 @@
4956
1. 引入 rookie_text2data 插件
5057
2. 完成基础参数配置
5158

52-
| 参数名 | 类型 | 必填 | 描述 | 多语言支持 |
53-
|-----------|----------|------|--------------------------------|---------------------------|
54-
| db_type | select | 是 | 数据库类型（MySQL/PostgreSQL） | 中/英/葡 |
55-
| host | string | 是 | 数据库主机地址 | 中/英/葡 |
56-
| port | number | 是 | 数据库端口（1-65535） | 中/英/葡 |
57-
| db_name | string | 是 | 目标数据库名称 | 中/英/葡 |
58-
| table_name| string | 否 | 多表逗号分隔（空则全库） | 中文含格式说明 |
59-
60-
3. 选择模型
61-
推荐使用`Qwen-max`模型，其他模型请自行尝试。不支持深度思考模型。
59+
| 参数名 | 类型 | 必填 | 描述 | 多语言支持 |
60+
|----------------|----------------|------|-------------------------------------------------------------|----------------|
61+
| db_type | select | 是 | 数据库类型（MySQL/PostgreSQL/Oracle/SQL Server/GaussDB/KingbaseES/DM） | 中/英/葡 |
62+
| host | string | 是 | 数据库主机地址 | 中/英/葡 |
63+
| port | number | 是 | 数据库端口（1-65535） | 中/英/葡 |
64+
| db_name | string | 是 | 目标数据库名称 | 中/英/葡 |
65+
| table_names | string | 否 | 多表逗号分隔（空则全库） | 中文含格式说明 |
66+
| schema_name | string | 否 | Schema名称（PostgreSQL默认为public，Oracle/DM默认为用户名大写） | 中/英/葡 |
67+
| username | string | 是 | 数据库用户名 | 中/英/葡 |
68+
| password | secret-input | 是 | 数据库密码 | 中/英/葡 |
69+
| model | model-selector | 是 | LLM 模型配置 | 中/英/葡 |
70+
| query | string | 是 | 自然语言查询语句 | 中/英/葡 |
71+
| limit | number | 否 | 查询结果限制（1-100000，默认100） | 中/英/葡 |
72+
| result_format | select | 否 | 结果格式（JSON/TEXT，默认JSON） | 中/英/葡 |
73+
| custom_prompt | string | 否 | 自定义提示词，用于微调查询生成 | 中/英/葡 |
74+
| with_comment | boolean | 否 | 在Schema元数据中包含数据库注释 | 中/英/葡 |
75+
76+
3. 选择模型 - 推荐使用 `Qwen-max` 模型，其他模型请自行尝试。不支持深度思考模型。
6277
4. 使用自然语言生成 SQL 查询语句
6378

6479
#### SQL执行组件
6580
1. 引入 rookie_excute_sql 插件
6681
2. 完成基础参数配置
6782

68-
| 参数名 | 类型 | 必填 | 描述 | 多语言支持 |
69-
|-----------|----------|------|--------------------------------|---------------------------|
70-
| db_type | select | 是 | 数据库类型（MySQL/PostgreSQL） | 中/英/葡 |
71-
| host | string | 是 | 数据库主机地址 | 中/英/葡 |
72-
| port | number | 是 | 数据库端口（1-65535） | 中/英/葡 |
73-
| db_name | string | 是 | 目标数据库名称 | 中/英/葡 |
74-
| sql | string | 是 | SQL 查询语句 | 中/英/葡 |
75-
76-
77-
3. 点击执行，执行 sql 语句
83+
| 参数名 | 类型 | 必填 | 描述 | 多语言支持 |
84+
|----------------|--------------|------|-------------------------------------------------------------|----------------|
85+
| db_type | select | 是 | 数据库类型（MySQL/PostgreSQL/Oracle/SQL Server/GaussDB/KingbaseES/DM） | 中/英/葡 |
86+
| host | string | 是 | 数据库主机地址 | 中/英/葡 |
87+
| port | number | 是 | 数据库端口（1-65535） | 中/英/葡 |
88+
| db_name | string | 是 | 目标数据库名称 | 中/英/葡 |
89+
| username | string | 是 | 数据库用户名 | 中/英/葡 |
90+
| password | secret-input | 是 | 数据库密码 | 中/英/葡 |
91+
| schema | string | 否 | Schema名称（PostgreSQL默认为public，Oracle/DM默认为用户名大写） | 中/英/葡 |
92+
| sql | string | 是 | 待执行的 SQL 语句 | 中/英/葡 |
93+
| result_format | select | 否 | 结果格式（JSON/TEXT/CSV，默认JSON） | 中/英/葡 |
94+
95+
3. 点击执行，执行 SQL 语句
96+
97+
### 数据库特定说明
98+
99+
#### 国产数据库支持
100+
- **GaussDB（高斯数据库）**：兼容 PostgreSQL 协议，使用 SCRAM-SHA-256 认证
101+
- **KingbaseES（人大金仓）**：兼容 PostgreSQL，支持基于 Schema 的组织方式
102+
- **DM（达梦数据库）**：兼容 Oracle，使用 Oracle 风格的 Schema 管理
103+
104+
#### Schema 配置说明
105+
- **PostgreSQL/GaussDB/KingbaseES**：默认 Schema 为 `public`，可自定义
106+
- **Oracle/DM**：默认 Schema 为用户名的大写形式（例如：用户 `admin` → Schema `ADMIN`）
107+
- **MySQL/SQL Server**：不需要配置 Schema 参数
108+
109+
#### 驱动依赖说明
110+
- **达梦数据库（DM）**：需要从达梦官方获取 dmPython 驱动并手动安装
111+
- **其他数据库**：所需驱动已在 requirements.txt 中配置，pip install 即可
78112

79113
### 许可证
80114

0 commit comments

Comments
 (0)