80 lines
6.0 KiB
Markdown
80 lines
6.0 KiB
Markdown
# 架构与组件
|
||
|
||
ChuSQL 由三个面向用户的程序、几个共享库与一份配置组成：
|
||
|
||
| 组件 | 作用 |
|
||
| ------------------------------- | -------------------------------------------------------------------- |
|
||
| `chusql-server` | 数据库服务：进程内装入引擎与存储动态库、独占数据目录，对外只开一个 TCP 端口 |
|
||
| `chusql-web` | Web 管理端：浏览器里的数据库 IDE，自己开 HTTP 端口，后端经 TCP 连 `chusql-server` |
|
||
| `csql` | 命令行客户端，经 TCP 连 `chusql-server` |
|
||
| `chusql-core/engine`（库） | SQL 解析、语义检查、优化与执行，链进 `chusql-server` |
|
||
| `chusql-core/storage`（动态库） | 存储：页面与索引、WAL、崩溃恢复 |
|
||
| `chusql-interface`（库） | 接口层：线上协议、配置与设置、口令与限流、语句构造、TCP 客户端与会话，`chusql-web` 与 `csql` 共用 |
|
||
| `chusql-core/model`（库） | 共享类型：表与列、结果集、权限枚举 |
|
||
|
||
安装时把可执行文件与存储动态库（`libchusql_core_storage.so` / `chusql_core_storage.dll`）放进同一个目录，
|
||
进程按 exe 所在目录就能找到库。
|
||
|
||
## 数据流
|
||
|
||
浏览器、`csql` 或别的程序 → TCP → `chusql-server` → 同一进程里调 `chusql-core/engine`
|
||
（经 FFI 再调 `chusql-core/storage` 动态库）→ 磁盘。
|
||
|
||
**数据目录只有 `chusql-server` 一个进程碰**：`chusql-web` 与 `csql` 自己不开存储，它们把 SQL 与数据字典请求
|
||
交给 TCP 服务执行，拿到结果再渲染。因此库文件同一时刻只有一个持有者；进程内的并发先用一把锁串起来，
|
||
完整事务与 MVCC 见后续计划。
|
||
|
||
`chusql-web` 是「自己开 HTTP 服务、同时又是 `chusql-server` 的 TCP 客户端」：浏览器只跟 Web 说话，
|
||
Web 后端在需要认证、鉴权、读数据或改数据的时候，才把请求发给 `chusql-server`。
|
||
|
||
三种用法共用同一份 [`chusql.toml`](config.md)、同一个管理员账号与同一张账号表——任意一端改的账号与权限，
|
||
另外两端立刻生效。
|
||
|
||
## 一次请求经过什么
|
||
|
||
1. 浏览器、命令行或别的程序发起 SQL；
|
||
2. 解析与语义检查（表/列是否存在、类型是否匹配、权限是否足够）在 `chusql-server` 里完成，不合格的语句不会落到磁盘；
|
||
3. 合格语句经 FFI 交给同一进程里的存储库；
|
||
4. 存储库读写页面与索引，写之前先记 WAL；
|
||
5. 结果原路返回。
|
||
|
||
## 数据在哪里
|
||
|
||
数据都在 `[storage] data_dir` 下。不写这个键就按平台惯例：Windows `%LOCALAPPDATA%\ChuSQL\data`，
|
||
Linux / macOS `${XDG_DATA_HOME:-~/.local/share}/chusql/data`。
|
||
|
||
| 目录 | 内容 |
|
||
| --------------------- | ---------------------------- |
|
||
| `system/` | 系统库：账号表与角色授权表 |
|
||
| `databases/<库名>/` | 各自建的库 |
|
||
|
||
服务启动后只建 `system`，**没有默认工作库**；其余库由你自己 `CREATE DATABASE` 创建。
|
||
|
||
## TCP 数据库服务（`chusql-server`）
|
||
|
||
给别的程序用的接口：一条 TCP 连接一条 SQL 会话，请求和应答都是**一行一个 JSON 对象**，编码 UTF-8。
|
||
|
||
| 请求 | 字段 | 应答 `status` |
|
||
| --------------- | --------------------------- | ---------------------------------------------------------------- |
|
||
| `hello` | `protocol`（可选，默认 1） | `hello`：带 `protocol`、`server` |
|
||
| `login` | `user`、`password` | `ok`：带 `user`、`admin` |
|
||
| `query` | `sql` | `result`：带 `columns`、`rows`、`rowCount`、`truncated`、`database` |
|
||
| `catalog` | — | `catalog`：带 `schemas`（表与列） |
|
||
| `databases` | — | `databases`：带库名列表 |
|
||
| `roles` | — | `roles`：带角色与授权视图 |
|
||
| `accounts` | — | `accounts`：带账号表（仅管理员） |
|
||
| `policy` | — | `policy`：带 `minLength`、`classes`（仅管理员） |
|
||
| `reload-policy` | — | `policy`：重新读设置里的口令策略（仅管理员） |
|
||
| `storage` | `request`（存储层的原始请求） | `storage`：带 `response`（存储层的原始应答，仅管理员） |
|
||
| `ping` | — | `pong` |
|
||
| `quit` | — | `bye`，随后连接关闭 |
|
||
|
||
方法名大小写不敏感，认不出的字段忽略。任何一端出错都回 `{"status":"error","code":...,"message":...}`
|
||
且**连接不断**，客户端可以接着发下一条；`code` 取值有 `bad_request`（协议号不符、SQL 为空、行太长）、
|
||
`unauthorized`（没登录就查询、口令不对）、`forbidden`、`too_many_attempts`（登录失败被限流）、
|
||
`too_large`、`no_database`、`not_found`、`query_error`、`conflict`、`storage_error`。
|
||
|
||
登录之前只能 `hello` / `ping` / `quit`；`storage`、`accounts`、`policy`、`reload-policy` 与系统库只对管理员开放。
|
||
每条连接各有一份会话，数据库选择（`USE <库>`）不跨连接。监听参数在 `[server]` 分区（见 [config.md](config.md)），
|
||
默认只听本机 `127.0.0.1:7777`。
|