yearning-cli 0.1.9

Yearning MySQL Audit Platform CLI Tool

yearning-cli

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

安装

uv sync

安装后 sql 命令全局可用。

如需安装到本机命令行：

uv tool install .

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

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

配置

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

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

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

命令速查

查看版本

sql --version

登录

sql login

浏览元数据

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

执行查询

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

导出结果到 ~/Downloads/

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

交互式 SQL Shell

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

Shell 内快捷命令：

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

MySQL 协议代理

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

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                 # 详细日志

连接方式：

# 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 查看调试信息：

sql query 'SELECT 1' -v

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

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

代理连接测试：

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