yearning-cli 0.1.5__tar.gz

yearning_cli-0.1.5/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

yearning_cli-0.1.5/.python-version

@@ -0,0 +1 @@
+3.11

yearning_cli-0.1.5/PKG-INFO

@@ -0,0 +1,192 @@
+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`，频繁关闭再启动代理时可减少重复准备工单

yearning_cli-0.1.5/README.md

@@ -0,0 +1,177 @@
+# 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`，频繁关闭再启动代理时可减少重复准备工单

yearning_cli-0.1.5/mysql_proxy/README.md

@@ -0,0 +1,32 @@
+# MySQL 协议代理
+
+MySQL 协议代理模块，让 DBeaver、Navicat、MySQL CLI 等客户端通过 Yearning 审计平台执行查询。
+
+通过 `sql proxy` 子命令启动。详见 [主 README](../README.md#mysql-协议代理)。
+
+## 原理
+
+```
+┌──────────────┐   MySQL协议    ┌──────────────┐   HTTP/WS      ┌──────────────┐
+│  MySQL 客户端 │ ────────────▶ │  sql proxy   │ ────────────▶ │  Yearning    │
+│  (Navicat等) │               │  (3307端口)   │                │  (审计平台)   │
+└──────────────┘               └──────────────┘                └──────────────┘
+```
+
+代理服务器默认监听 `0.0.0.0:3307`，将 MySQL 协议转换为 Yearning API 调用。需要仅允许本机访问时可启动 `sql proxy --host 127.0.0.1`；需要 IPv6 全网卡监听时可使用 `sql proxy --host ::`。
+
+## 数据源切换
+
+连接用户名 = 数据源名称。免密码登录，自动解析数据源：
+
+| 用户名 | 行为 |
+|--------|------|
+| `数据源名称` | 精确匹配该数据源 |
+| `root` / 任意不存在的名称 | 回退到 `~/.sqlrc` 配置的默认数据源 |
+
+密码字段无需填写，任意值均可。
+
+## 前提条件
+
+1. 已运行 `sql login` 登录 Yearning，或已配置 `YEARNING_USER`/`YEARNING_PASS`、`~/.sqlrc` 的 `yearning_user`/`yearning_pass` 供 token 失效时自动登录
+2. `~/.sqlrc` 配置了默认数据源（用于用户名不匹配时的回退）

yearning_cli-0.1.5/mysql_proxy/__init__.py

@@ -0,0 +1 @@
+"""MySQL protocol proxy — connect MySQL clients to Yearning audit platform."""