# sql5 v3.2 - Web-based Database Management Interface
## Overview
v3.2 新增 Web 介面，使用 FastAPI 實現：
```
┌─────────────────────────────────────────────────────────────┐
│ sql5 Web Admin │
├─────────────────────────────────────────────────────────────┤
│ Tables │ users │ posts │ comments │
│ ──────── │ ──────── │ ─────── │ ──────── │
│ │ id (PK) │ id (PK) │ id (PK) │
│ │ name │ title │ post_id │
│ │ email │ content │ content │
│ │ created_at │ author_id │ user_id │
├─────────────────────────────────────────────────────────────┤
│ Query │
│ ──────────────────────────────────────────────────────── │
│ SELECT * FROM users WHERE id > 0 │
│ │
│ [Execute] │
├─────────────────────────────────────────────────────────────┤
│ Results (3 rows) │
│ ──────────────────────────────────────────────────────── │
│ id │ name │ email │ created_at │
│ ─── │ ────── │ ────────────────── │ ─────────────────── │
│ 1 │ Alice │ alice@example.com │ 2026-01-01 10:00:00 │
│ 2 │ Bob │ bob@example.com │ 2026-01-02 10:00:00 │
│ 3 │ Carol │ carol@example.com │ 2026-01-03 10:00:00 │
└─────────────────────────────────────────────────────────────┘
```
## Tech Stack
- **Backend**: FastAPI (Python)
- **Frontend**: Vanilla JS + CSS
- **Database**: sql5 (via subprocess)
## Features
### Core Functionality
1. **Table Browser** - 瀏覽所有表格結構和資料
2. **SQL Editor** - 線上 SQL 編輯器和查詢執行
3. **Data Editor** - 視覺化資料編輯（新增/修改/刪除）
4. **Import/Export** - CSV/JSON 匯入匯出
## Changes from v3.1
- **New**: FastAPI web server mode (`python -m sql5 --http`)
- **New**: Web admin UI
- **New**: HTTP REST API endpoints
- **Version**: 3.2.0
## Architecture
```
python -m sql5 --http 8080
│
▼
┌──────────────────────────────────────────┐
│ FastAPI Server │
│ ┌────────────────────────────────────┐ │
│ │ Static Files (HTML/CSS/JS) │ │
│ │ - /static/index.html │ │
│ │ - /static/app.js │ │
│ │ - /static/styles.css │ │
│ └────────────────────────────────────┘ │
│ ┌────────────────────────────────────┐ │
│ │ REST API │ │
│ │ GET /api/tables │ │
│ │ GET /api/tables/:name │ │
│ │ POST /api/execute │ │
│ └────────────────────────────────────┘ │
└──────────────────────────────────────────┘
│ JSON stdio
▼
┌──────────────────────────────────────────┐
│ sql5 --server (Rust binary) │
└──────────────────────────────────────────┘
```
┌─────────────────────────────────────────────────────────────┐
│ sql5 Web Admin │
├─────────────────────────────────────────────────────────────┤
│ Tables │ users │ posts │ comments │
│ ──────── │ ──────── │ ─────── │ ──────── │
│ │ id (PK) │ id (PK) │ id (PK) │
│ │ name │ title │ post_id │
│ │ email │ content │ content │
│ │ created_at │ author_id │ user_id │
│ │ │ created_at │ created_at │
├─────────────────────────────────────────────────────────────┤
│ Query │
│ ──────────────────────────────────────────────────────── │
│ SELECT * FROM users WHERE id > 0 │
│ │
│ [Execute] │
├─────────────────────────────────────────────────────────────┤
│ Results (3 rows) │
│ ──────────────────────────────────────────────────────── │
│ id │ name │ email │ created_at │
│ ─── │ ────── │ ────────────────── │ ─────────────────── │
│ 1 │ Alice │ alice@example.com │ 2026-01-01 10:00:00 │
│ 2 │ Bob │ bob@example.com │ 2026-01-02 10:00:00 │
│ 3 │ Carol │ carol@example.com │ 2026-01-03 10:00:00 │
└─────────────────────────────────────────────────────────────┘
```
## Features
### Core Functionality
1. **Table Browser** - 瀏覽所有表格結構和資料
2. **SQL Editor** -線上 SQL 編輯器和查詢執行
3. **Data Editor** - 視覺化資料編輯（新增/修改/刪除）
4. **Schema Designer** - 視覺化建立表格
5. **Import/Export** - CSV/JSON 匯入匯出
### Server Modes
| HTTP | `sql5 --http <port>` | Web admin interface |
| WebSocket | `sql5 --websocket <port>` | Real-time updates |
## Changes from v3.1
- **New**: Web server mode (`--http`)
- **New**: Web admin UI (embedded static files)
- **New**: HTTP REST API endpoints
- **Version**: 3.2.0
## Architecture
### Components
```
sql5 --http 8080
│
▼
┌──────────────────────────────────────────┐
│ HTTP Server │
��� ┌────────────────────────────────────┐ │
│ │ Static Files (HTML/CSS/JS) │ │
│ │ - index.html │ │
│ │ - app.js │ │
│ │ - styles.css │ │
│ └────────────────────────────────────┘ │
│ ┌────────────────────────────────────┐ │
│ │ REST API │ │
│ │ GET /api/tables │ │
│ │ GET /api/tables/:name │ │
│ │ POST /api/query │ │
│ │ POST /api/execute │ │
│ └────────────────────────────────────┘ │
└──────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────┐
│ Executor + Catalog │
└──────────────────────────────────────────┘
```
### REST API
| GET | `/api/tables` | List all tables |
| GET | `/api/tables/:name` | Get table schema |
| POST | `/api/execute` | Execute SQL query |
| GET | `/api/tables/:name/data` | Get table data |
| POST | `/api/tables/:name/insert` | Insert row |
| PUT | `/api/tables/:name/update/:rowid` | Update row |
| DELETE | `/api/tables/:name/delete/:rowid` | Delete row |
### Request/Response Format
```json
// POST /api/execute
{"sql": "SELECT * FROM users", "params": []}
// Response
{"ok": true, "columns": ["id", "name"], "rows": [[1, "Alice"]], "affected": 0}
```
## Installation
```bash
cargo build --release
./target/release/sql5 --http 8080
```
Open browser: http://localhost:8080
## Usage
```bash
# Start web server on port 8080
sql5 --http 8080
# Start with database file
sql5 --http 8080 mydb.db
# Custom port
sql5 --http 9000
```
## Web Interface Features
### 1. Table Browser
- 左侧边栏显示所有表格列表
- 点击表格显示结构（列名、类型、约束）
- 显示前 100 行数据
- 分页导航
### 2. SQL Editor
- Monaco-style code editor
- SQL 语法高亮
- 执行按钮 (Ctrl+Enter)
- 结果显示区域
- 查询历史记录
### 3. Quick Actions
- `.tables` - 显示所有表格
- `.schema table` - 显示表格结构
- 运行常见查询模板
## Technology Stack
- **HTTP Server**: tokio + hyper
- **Static Files**: 内嵌 dist/ 目录
- **Frontend**: Vanilla JS + CSS (no framework)
- **Database**: sql5 native
## File Structure
```
src/
├── main.rs # CLI + server 入口
├── interface/
│ ├── http.rs # HTTP server
│ ├── server.rs # JSON stdio server
│ └── websocket.rs # WebSocket server
└── web/
├── mod.rs # Web module
├── static.rs # Embedded static files
└── templates.rs # HTML templates
web/
├── index.html # Main page
├── app.js # Frontend logic
└── styles.css # Styles
```
## UI Mockup
### Main Layout
```
┌──────────────────────────────────────────────────────────────────┐
│ [sql5] Database: mydb.db [New Table] [Import] [Export] [?] │
├────────────┬─────────────────────────────────────────────────┤
│ │ │
│ Tables │ Schema / Query │
│ ─────── │ ───────────────────────────────────────────── │
│ □ users │ Tab: [Structure] [Data] [Indexes] [Foreign Keys]│
│ □ posts │ │
│ □ comments│ id INTEGER PRIMARY KEY │
│ │ title TEXT NOT NULL │
│ System │ content TEXT │
│ ─────── │ created_at TIMESTAMP │
│ □ sqlite_ │ │
│ master │ ───────────────────────────────────────────── │
│ │ │
│ [+Table] │ SQL: [ ] │
│ │ [Execute] [Format] [Clear] │
│ │ ───────────────────────────────────────────── │
│ │ Results: 3 rows in 0.001s │
│ │ id │ title │ content │ created_at │
│ │ 1 │ Hello │ World... │ 2026-01-01 │
│ │ 2 │ Rust │ Is awesome... │ 2026-01-02 │
│ │ 3 │ sql5 │ Database... │ 2026-01-03 │
│ │ │
│ │ [< Prev] Page 1 of 1 [Next >] │
└────────────┴─────────────────────────────────────────────────┘
```
## Color Scheme
- **Background**: #1e1e2e (dark)
- **Sidebar**: #181825
- **Accent**: #89b4fa (blue)
- **Success**: #a6e3a1 (green)
- **Error**: #f38ba8 (red)
- **Text**: #cdd6f4
- **Border**: #313244
## Keyboard Shortcuts
| Ctrl+Enter | Execute query |
| Ctrl+S | Save query |
| Ctrl+/.toggle | Comment line |
| Escape | Clear selection |
## Security Considerations
- Only localhost access by default
- Optional password protection
- Read-only mode option
- SQL injection prevention via parameterized queries
## See Also
- [v3.1.md](./v3.1.md) - Python CLI
- [v3.0.md](./v3.0.md) - WebSocket server
- [v2.0.md](./v2.0.md) - Client-server architecture