Metadata-Version: 2.4
Name: yearning-cli
Version: 0.1.5
Summary: Yearning MySQL Audit Platform CLI Tool
Project-URL: Homepage, https://github.com/la3rence/yearning-cli
Project-URL: Repository, https://github.com/la3rence/yearning-cli
Author: la3rence
License-Expression: MIT
Requires-Python: >=3.11
Requires-Dist: msgpack>=1.1.2
Requires-Dist: openpyxl>=3.1
Requires-Dist: requests>=2.31
Requires-Dist: websocket-client>=1.9.0
Description-Content-Type: text/markdown

# yearning-cli

Yearning MySQL 审计平台命令行工具。无需打开 Web 界面，直接在终端执行 SQL 查询、浏览元数据、导出结果。

## 安装

```bash
uv sync
```

安装后 `sql` 命令全局可用。

如需安装到本机命令行：

```bash
uv tool install .
```

如果本机已安装过旧版本，使用当前项目代码强制替换：

```bash
uv tool install --force --reinstall .
hash -r
sql --version
```

## 配置

### 1. 环境变量（Yearning 连接信息）

```bash
export YEARNING_URL=http://your-yearning-server
export YEARNING_USER=your_username
export YEARNING_PASS=your_password
```

### 2. 默认数据源（~/.sqlrc）

创建 `~/.sqlrc` 设置默认数据源和数据库，避免每次手动指定：

```
source: 你的数据源名称
database: 你的数据库名
```

如果希望 token 过期后自动重新登录，也可以把 Yearning 登录凭据放到 `~/.sqlrc`：

```
yearning_user: your_username
yearning_pass: your_password
```

配置后，所有子命令会自动使用这些默认值。

## 命令速查

### 查看版本

```bash
sql --version
```

### 登录

```bash
sql login
```

### 浏览元数据

```bash
sql sources                   # 列出所有数据源
sql sources --idc 生产         # 按 IDC 筛选
sql databases                 # 列出默认数据源的数据库
sql databases "数据源名称"     # 列出指定数据源的数据库
sql tables                    # 列出默认库的表
sql tables "数据源" 数据库名   # 列出指定库的表
```

### 执行查询

```bash
sql query 'SELECT * FROM some_table LIMIT 10'
sql query 'SELECT ...' "数据源" 数据库名   # 覆盖默认值
sql query 'SELECT ...' --json              # JSON 输出
sql query 'SELECT ...' --timeout 60        # 超时 60 秒
```

### 导出结果到 ~/Downloads/

```bash
sql query 'SELECT ...' -o              # 默认 xlsx
sql query 'SELECT ...' -o csv          # CSV 格式
sql query 'SELECT ...' -o json         # JSON 格式
```

### 交互式 SQL Shell

```bash
sql shell
sql shell "数据源名称" 数据库名         # 覆盖默认值
```

Shell 内快捷命令：

| 命令 | 说明 |
|------|------|
| `\s` / `\d` | 列出所有数据库 |
| `\s dbname` | 切换数据库 |
| `\t` | 列出当前库所有表 |
| `exit` / `quit` / `\q` | 退出 |

### MySQL 协议代理

启动代理服务器，让 DBeaver/Navicat/MySQL CLI 等客户端通过 Yearning 执行查询：

```bash
sql proxy                    # 启动代理（默认监听 0.0.0.0:3307）
sql proxy --port 3308        # 自定义端口
sql proxy --host 127.0.0.1   # 仅允许本机连接
sql proxy --host ::          # 监听 IPv6 全网卡（系统支持时可同时接受 IPv4）
sql proxy -v                 # 详细日志
```

连接方式：

```bash
# MySQL CLI
mysql -h 127.0.0.1 -P 3307 -u 数据源名 数据库名
# 反向代理或其他机器请连接运行 sql proxy 的机器 IP，例如 192.168.x.x:3307

# DBeaver / Navicat 等图形客户端
# Host: 127.0.0.1 / 机器局域网 IP / 反代入口  Port: 3307  Username: 数据源名称  Password: 留空
```

代理参数：

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--host` | 绑定地址；IPv4 全网卡为 `0.0.0.0`，IPv6 全网卡为 `::` | 0.0.0.0 |
| `--port` | 监听端口 | 3307 |
| `--source` | 数据源名称或 ID | 从 ~/.sqlrc 读取 |
| `--database` | 默认数据库名 | 从 ~/.sqlrc 读取 |
| `--url` | Yearning URL | 从环境变量读取 |
| `--user` | 要求认证的用户名 | 无 |
| `--password` | 要求的认证密码 | 无 |

### 调试

任意命令加 `-v` 或 `--verbose` 查看调试信息：

```bash
sql query 'SELECT 1' -v
```

本地开发阶段不需要重新安装，可直接用 `uv run` 运行当前工作区代码：

```bash
uv run sql proxy -v --port 3307
uv run sql query 'SELECT 1'
```

代理连接测试：

```bash
mysql -h 127.0.0.1 -P 3307 -u 数据源名 数据库名 -e "SELECT 1"
```

## 工作原理

- 通过 HTTP API 登录 Yearning 获取 Bearer Token
- 查询前自动创建查询工单（支持自动审批模式）
- 通过 WebSocket + msgpack 协议执行 SQL 并获取结果
- `sql proxy` 将 MySQL 协议转换为 Yearning API 调用，兼容各类 MySQL 客户端
- 代理会延迟初始化 Yearning，并缓存短期元数据和查询工单状态，降低客户端反复连接时的等待
- Token 持久化到 `~/.yearning_state`，后续命令自动复用；如果 token 过期或无效，会使用 `YEARNING_USER`/`YEARNING_PASS` 或 `~/.sqlrc` 中的 `yearning_user`/`yearning_pass` 自动登录，最多尝试 2 次
- 查询工单可用状态也会短期写入 `~/.yearning_state`，频繁关闭再启动代理时可减少重复准备工单
