# 命令与选项

## 一共有几个可执行文件

| 命令 | 作用 | 选项 |
| ---- | ---- | ---- |
| `chusql-storage` | 存储进程：页面与索引、WAL | 只有 `--config <path>` |
| `chusql-web` | Web 管理端：REST 接口 + 浏览器里的数据库 IDE | 见「`chusql-web` 选项」 |
| `csql` | 命令行客户端，直连存储进程，不经过 HTTP | 见「`csql` 选项」 |
| `csql-web` | 一键启动器：按配置拉起存储进程 + Web，日志写 `<install-dir>/logs` | 无选项（`host`/`port` 从配置读） |

四个命令共用同一份 [`chusql.toml`](config.md)；`--config` 都是用来临时读另一份配置的。

## `csql` 选项

    csql [options]

| 选项 | 默认 | 说明 |
| ---- | ---- | ---- |
| `-u, --user USER` | 配置里的管理员 | 用这个账号登录 |
| `-p, --password` | — | 强制交互输入口令，忽略配置里的 |
| `-d, --database DB` | 不选（启动后没有默认库） | 登录后直接选中哪个库 |
| `-f, --format FORMAT` | `table` | 输出格式：`table` / `json` / `csv` |
| `-e, --execute SQL` | — | 跑一条语句就退出（脚本化用） |
| `--history FILE` | `~/.chusql_history` | 历史文件位置 |
| `--pipe NAME` | 配置 `[server] pipe_name` | 端点名（Windows 具名管道 / Unix 套接字文件） |
| `--storage SERVER` | — | 端点没人应答时，拉起这个存储进程可执行文件 |
| `--config FILE` | 固定位置的 `chusql.toml` | 读另一份配置 |
| `-h, --help` | — | 帮助 |

脚本化示例：

    csql -e "SELECT count(*) FROM orders" -f json
    csql -u analyst -p -d sales -f csv -e "SELECT * FROM orders LIMIT 5"

## 交互模式

- 提示符 `chusql>`；语句以**分号**结尾，可以跨多行；上下键翻历史（默认存 `~/.chusql_history`）。
- 退出码：语句出错时非 0，方便在脚本里判断。

### 元命令

| 元命令 | 作用 |
| ------ | ---- |
| `\q` `\quit` | 退出 |
| `\?` `\h` `\help` | 帮助 |
| `\l` `\list` | 列出数据库 |
| `\dt` `\d` | 列出当前库的表 |
| `\d <表>` | 看表结构 |
| `\dr` `\roles` | 角色总览：授权对象与成员（管理员专属，等价于 Web 的 `GET /api/roles`） |
| `\c <库>` | 切换数据库 |
| `\f` `\format <fmt>` | 切换输出格式：`table` / `json` / `csv` |

普通身份用 `\dt` 时只会看到自己有 `SELECT` 权限的表，系统表永远不出现。

## 账号与权限

账号：root（配置里的 `user` / `password` 决定，见 [config.md](config.md)）是管理员，其余都是普通账号，
默认**零权限**，只能看到被授权的表。系统库 `system`（账号表在里面）只有管理员能进。

服务启动后**只有系统库**，没有任何默认工作库：自己 `CREATE DATABASE shop` 再 `USE shop`。
没选库时只有"限定名"语句能跑（`SELECT * FROM shop.items`），裸表名（`SELECT * FROM items`）会报
`no database selected`——先把库选上。

    CREATE USER alice IDENTIFIED BY 'secret';    -- 普通账号，口令是明文，服务端加盐派生
    ALTER USER alice IDENTIFIED BY 'new-secret'; -- 改口令
    DROP USER alice;

`CREATE USER` / `ALTER USER` / `DROP USER` 只有管理员能执行（Web 端在 SQL 控制台，命令行直接跑）。

权限按**角色**给，三句话：

    CREATE ROLE analyst;                        -- 建角色（平的角色，不可继承）
    GRANT SELECT, INSERT ON orders TO analyst;  -- 授权：对象可以是表名或 *
    GRANT analyst TO alice;                     -- 把角色给账号
    REVOKE INSERT ON orders FROM analyst;       -- 收回权限
    REVOKE analyst FROM alice;                  -- 收回角色
    DROP ROLE analyst;

| 权限 | 覆盖 |
| ---- | ---- |
| `SELECT` | `SELECT`（含 JOIN、投影、`WHERE` 里的子查询） |
| `INSERT` | `INSERT`（含 `VALUES` 里的子查询） |
| `UPDATE` | `UPDATE`（含赋值与 `WHERE` 里的子查询） |
| `DELETE` | `DELETE`（含 `WHERE` 里的子查询） |
| `ALL` | 上面四种，等价于逐条授权 |

- 对象写 `*` 表示当前库里所有表；写表名时按**当前库**限定（在 `sales` 库执行 `GRANT ... ON orders`
  授权的是 `sales.orders`），换库要重新授权。
- 管理员（root）隐式拥有全部权限，不用授权；DDL（建表、建索引等）一律只有管理员能做。
- 角色语句本身只有管理员能跑；普通账号跑 `\dr` / `GET /api/roles` 会被拒（`administrator required`）。
- 授权变更立即生效；已经登录的会话不会被踢下线。
- 当前限制：没有列级授权，没有 `WITH GRANT OPTION`，角色不可继承，也没有自助查询（普通账号不能自己
  看自己的授权，得问管理员）。

Web 端对应的接口是 `/api/roles` 系列（`GET` 列表、`POST` 建角色、`DELETE /api/roles/:name` 删角色、
`POST/DELETE /api/roles/:name/grants` 授权/收权、`POST/DELETE /api/roles/:name/members[/:user]` 成员），
全部管理员专属。

## `chusql-web` 选项

    chusql-web [options]

| 选项 | 对应配置键 | 默认 |
| ---- | ---------- | ---- |
| `--config FILE` | — | 固定位置的 `chusql.toml` |
| `--host H` | `[web] host` | `127.0.0.1` |
| `--port N` | `[web] port` | `7777` |
| `--static DIR` | `[web] static_dir` | `static` |
| `--user NAME` | `[web] user` | `root` |
| `--storage SERVER` | `[web] storage_server` | — |
| `--cookie-secure BOOL` | `[web] cookie_secure` | `false` |
| `--body-limit N` | `[web] body_limit` | `65536` |
| `--session-idle N` | `[web] session_idle` | `28800` |
| `--session-max N` | `[web] session_max` | `86400` |
| `--login-max-attempts N` | `[web] login_max_attempts` | `5` |
| `--login-window N` | `[web] login_window` | `300` |
| `--page-size N` | `[web] rows_per_page` | `25` |
| `--max-page-size N` | `[web] max_page_size` | `500` |
| `--max-rows N` | `[web] max_rows` | `1000` |
| `--max-sql-length N` | `[web] max_sql_length` | `20000` |
| `--seed BOOL` | `[web] seed` | `false` |
| `-h, --help` | — | 帮助 |

REST 接口（界面的一键操作全走结构化接口）：

| 分组 | 接口 |
| ---- | ---- |
| 探活（无需登录） | `GET /api/health`、`GET /api/status` |
| 会话 | `POST /api/login`、`POST /api/logout`、`GET /api/session` |
| 设置 | `GET`/`PUT /api/settings`、`GET`/`PUT /api/ui-settings` |
| 库 | `GET`/`POST /api/databases`、`DELETE /api/databases/:name` |
| 表 | `GET`/`POST /api/tables`、`GET`/`DELETE /api/tables/:t` |
| 行 | `GET`/`POST /api/tables/:t/rows`、`PATCH`/`DELETE /api/tables/:t/rows/:id` |
| 索引与列 | `POST /api/tables/:t/indexes`、`DELETE /api/tables/:t/indexes/:col`、`DELETE /api/tables/:t/columns/:col` |
| 演示数据 | `POST /api/demo-data` |
| SQL 控制台 | `POST /api/query`（`CREATE USER` / `CREATE ROLE` / `GRANT` 也在这里跑） |
| 角色 | `GET`/`POST /api/roles`、`DELETE /api/roles/:name`、`POST`/`DELETE /api/roles/:name/grants`、`POST`/`DELETE /api/roles/:name/members[/:user]` |

除探活、登录和首页（`GET /`、`GET /static/:file`）外都要带会话 Cookie。选库用 `X-ChuSQL-Database` 头：
**不带这个头就是"没选库"**，此时只有限定名语句（`db.table`）能跑，裸表名会得到 400 `no_database`；
`GET /api/databases` 和 `POST`/`DELETE /api/databases/:name` 不需要选库。普通身份碰 `system` 库一律 403。