# AGENTS.md - sql5 開發規範
## 專案資訊
- **專案**: sql5 v3.7.0 (SQLite 相容資料庫，含 CJK FTS5 全文檢索)
- **Edition**: Rust 2024 (需要 nightly 或近期 stable)
- **架構**: Client-Server 模式 (Python client + Rust server)
## 快速開始
```bash
cd /Users/Shared/ccc/project/sql5
# 編譯
cargo build --release
# 執行全部測試 (推薦)
./test.sh
```
## 常用指令
| `cargo build` | 編譯 debug 版 (target/debug/sql5) |
| `cargo build --release` | 編譯 release 版 (target/release/sql5) |
| `cargo check` | 型別檢查 (不編譯) |
| `cargo test` | 執行所有單元測試 (353 tests) |
| `./test.sh` | **執行全部測試** (Rust + CLI + Python) |
| `./shtest.sh` | CLI 整合測試 (114 tests) |
| `./pub.sh <version> pypi` | 上傳到 PyPI（自動更新版本號） |
| `./pub.sh <version> github` | 建立 GitHub tag 觸發 CI 發布（自動更新版本號） |
## 測試說明
### test.sh (全部測試)
執行六個階段：
1. **Build** - 編譯 Rust release binary
2. **Rust unit tests** - `cargo test` (353 tests)
3. **CLI integration tests** - `./shtest.sh` (114 tests)
4. **Python pytest** - pytest (48 tests, 5 skipped)
5. **Python client test** - sql5test.py
6. **WebSocket test** - websocket_test.py
### 測試結果
```
[PASS] Rust unit tests (cargo test) — 353 passed
[PASS] CLI integration tests (shtest.sh) — 114 passed
[PASS] Python pytest tests — 48 passed, 5 skipped
[PASS] Python client test (subprocess) — PASSED
[PASS] WebSocket test (v3.0) — PASSED
```
## 專案架構
```
src/
├── main.rs # CLI + server 入口
├── parser/ # SQL 解析與 AST
│ ├── lexer.rs
│ ├── parser.rs
│ └── ast.rs
├── planner/ # 查詢規劃與執行
│ ├── planner.rs
│ ├── executor.rs
│ ├── plan.rs
│ ├── transaction.rs
│ └── datetime.rs
├── btree/ # B+Tree 索引實作
├── table/ # 表格管理
├── pager/ # 儲存引擎 (含 WAL)
├── catalog/ # 系統目錄
├── fts/ # FTS5 全文檢索
│ ├── fts_table.rs
│ ├── tokenizer.rs # CJK 分詞
│ └── index.rs
└── interface/
├── repl.rs # REPL 模式
└── server.rs # Server 模式 (JSON stdio)
```
## Python Client
```
sql5_pypi/
├── sql5/
│ ├── __init__.py
│ ├── client.py # Python DB-API client
│ ├── _binary.py # Binary 下載
│ └── __main__.py
├── tests/
│ ├── test_sql5.py # pytest 測試 (26 tests)
│ └── test_compare_sqlite.py # sqlite3 API 相容性測試 (22 tests)
└── dist/ # PyPI 發布目錄
```
### 執行 Python 測試
```bash
cd sql5_pypi
export SQL5_BINARY=../../target/release/sql5
python -m pytest tests/ -v
```
## v2.0 Client-Server Protocol
Server 透過 stdin/stdout 接收/輸出 JSON：
```json
// Request
{"method": "execute", "sql": "SELECT 1"}
// Response
{"ok": true, "columns": ["1"], "rows": [[1]], "affected": 0, "lastrowid": null}
```
## REPL 用法
```bash
./target/release/sql5 # In-memory REPL
./target/release/sql5 my.db # 開啟資料庫檔案
sql5> SELECT 1
sql5> .tables
sql5> .schema my_table
sql5> .quit
```
## 程式碼品質規範
依據 `ccc_code_skill.md`:
1. **模組化**: 程式超過 1000 行需強制分模組 (src/ 下 26 個模組)
2. **零警告**: 提交前確保 `cargo build` 零警告
3. **版本文件**: 每個重要功能完成後需在 `_doc/vX.X.md` 記錄
## 版本文件
每次發布新版本需在 `_doc/vX.X.md` 建立文件，參考現有範例 (v1.1–v2.0)。
## 檔案結構
```
sql5/
├── src/ # Rust 原始碼 (26 modules)
├── tests/ # Integration tests
├── sql5_pypi/ # Python package
│ ├── sql5/ # Python module
│ ├── tests/ # pytest tests
│ │ ├── test_sql5.py # 26 tests
│ │ └── test_compare_sqlite.py # 22 tests (sqlite API compatibility)
│ └── _bak/ # 備份檔案
├── _doc/ # 版本文件 (v3.7, v3.0, ...)
├── _bak/ # 備份 (test.sh, test.py, server.sh)
├── Cargo.toml
├── test.sh # 全部測試 (主要指令)
├── shtest.sh # CLI 整合測試 (114 tests)
├── pytest.sh # Python pytest
├── pub.sh # 發布腳本 (pypi/github)
└── sql5web.sh # WebSocket 測試
```
## 備份檔案 (_bak/)
已移至 _bak 的過時檔案：
- `server.sh` - 舊的簡單測試
- `test.sh` - 已被新的 test.sh 取代
- `test.py` - 已被 pytest 取代
- `sql5_pypi/test_sql5_server.py` - 已被 pytest 取代
- `sql5_pypi/test_server.sh` - 已被 pytest 取代