命令行与 Agent 接口参考
在终端脚本或 Claude Code、Codex 等命令行 Agent 中直接复用已保存的数据库连接,跑通整库数据字典、只读 SQL、流式导出与四大 NoSQL 查询。
配置 PATH 与一键生成 Agent Skill #
对于原生具备终端执行能力的工具(如 Claude Code、Codex 或你自己的巡检脚本),直接调用 dataomni cli 甚至无需注册常驻 MCP 服务——不占上下文工具表,输出结构化 JSON,且与 MCP 共用同一套钥匙串开放凭证、生产库隐身与只读事务防线。
# macOS 建立命令行软链(Linux .deb / .rpm 安装后已在 /usr/bin/dataomni)
ln -sf /Applications/DataOmni.app/Contents/MacOS/dataomni ~/.local/bin/dataomni
# 输出完整 SKILL.md,可直接存进 Claude Code / Codex 的 skills 目录
dataomni cli guide
Windows 终端退出码小贴士
Windows 发布版主程序采用 GUI 子系统,在 PowerShell / CMD 直接手敲命令时终端不会等待进程结束;若脚本里需要读取 $LASTEXITCODE,请接管道(如 dataomni cli connections | Out-String)或用 cmd /c start /wait。AI Agent 本身经管道调用子进程,完全不受影响。
关系库结构读取、只读查询、导出与备份 #
支持按连接名称或连接 ID 调用;长 SQL 可用 - 代替语句参数从标准输入读取。export 与 backup 只允许写入全新的目标路径,绝不覆盖磁盘上已有文件。
| 子命令 | 功能与默认边界 |
|---|---|
| dataomni cli connections | 列出当前已对 Agent 开放的非生产连接及数据库类型。 |
| dataomni cli dictionary <连接> | 输出整库 Markdown 数据字典(表、列、类型、主外键),最适合写 SQL 前先读一遍。 |
| dataomni cli schema <连接> [<表>] | 列出整库表与视图,或读取指定单表的列、索引与外键。 |
| dataomni cli ddl <连接> <表> | 获取数据库自身保存的对象定义原文(PostgreSQL 仅视图有原文,其余库含表与视图)。 |
| dataomni cli query <连接> "<SQL>" | 执行单条只读语句(默认 --limit 200,上限 10000;默认 --timeout 30 秒)。 |
| dataomni cli explain <连接> "<SQL>" | 获取估算执行计划(禁止 ANALYZE,不实际执行语句)。 |
| dataomni cli export <连接> "<SQL>" --out <文件> | 在只读事务内流式导出完整结果到新 CSV 或 JSON(--format json)文件(默认 300 秒)。 |
| dataomni cli backup <连接> --out <路径> | 按应用内置逻辑做只读备份(SQLite VACUUM INTO、DuckDB EXPORT、pg_dump、mysqldump、mongodump)。 |
| dataomni cli csv-preview <文件> | 离线嗅探本地 CSV 分隔符与编码(UTF-8 / GB18030),标出字段数异常行。 |
| dataomni cli test <连接> | 测试连接;失败时在 error.diagnosis 返回域名解析与端口探测结果。 |
$ dataomni cli dictionary shop_dev
$ dataomni cli query shop_dev "SELECT status, COUNT(*) FROM orders GROUP BY status" --limit 50
$ dataomni cli export shop_dev - --out /tmp/orders_summary.json --format json < report.sql
MongoDB、Redis、Neo4j 与 Elasticsearch 只读子命令 #
四类非关系型数据库各自提供符合原生习惯的只读子命令,每一种都有独立的服务端/词法双重只读校验:
# MongoDB(沿用 mongosh 写法,解析期直接拒绝含 $out / $merge 的聚合管道)
dataomni cli mongo app_mongo collections
dataomni cli mongo app_mongo find shop.orders '{ status: "paid" }' --limit 20
# Redis(--db N 放在操作名前;command 先查服务端 COMMAND INFO 确认带 readonly 旗标)
dataomni cli redis cache_dev --db 0 scan "session:*"
dataomni cli redis cache_dev get "session:42"
# Neo4j(先发 EXPLAIN 确认服务端判定查询类型为 r,再在只读路由事务内运行)
dataomni cli neo4j graph_dev labels
dataomni cli neo4j graph_dev run "MATCH (u:User)-[:BOUGHT]->(p) RETURN u.id, p.sku LIMIT 25"
# Elasticsearch / OpenSearch(按路径段白名单放行 GET/HEAD 及 _search、_count、_msearch 等查询)
dataomni cli es search_dev indices
dataomni cli es search_dev request POST /orders/_search '{"size":10,"query":{"match_all":{}}}'
JSON 输出结构(schema: 1)与退出码契约 #
标准输出默认打印顶层带 "schema": 1 的 JSON(传 --format table 可切为终端对齐表格;dictionary 固定输出 Markdown)。报错统一写向标准错误 {"schema": 1, "error": {"kind": "...", "message": "..."}},并通过 0–4 退出码明确区分「改写 SQL 重试」与「权限红线切勿重试」:
| 退出码 | 类别 | 调用方 / Agent 应对动作 |
|---|---|---|
| 0 | 执行成功 | 正常解析 stdout JSON(或 dictionary 的 Markdown)。 |
| 1 | 数据库执行报错或超时 | 阅读 error.message,修正表名、列名、语法或收窄查询条件。 |
| 2 | 参数用法错误或连接不存在 | 修正命令行参数;连接报 not_found 说明未创建或未对 Agent 开放。 |
| 3 | 被只读权限门拒绝 | 立即停止换花样重试——属于写操作、DDL 或多条语句,命令行没有任何参数可放宽该限制。 |
| 4 | 连接不可达或缺凭据授权 | 检查网络(看 error.diagnosis)或提示用户在系统钥匙串弹窗点「始终允许」(CLI 最多等 10 秒)。 |