DBX CLI 数据库安全查询与 Schema 探索指南面向 AI Agent 的命令行操作手册【免费下载链接】dbx25 MB lightweight cross-platform database client for 90 databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 90 数据库提供桌面端、Docker、CLI、内置 AI 助手和 MCP Server。项目地址: https://gitcode.com/gh_mirrors/dbx7/dbx本文以skills/dbx/SKILL.md为骨架结合仓库中crates/dbx-cli、crates/dbx-core等源码实现系统讲解 DBX CLI 的安装验证、连接管理、Schema 探索、只读查询、AI 提示词上下文生成以及贯穿始终的安全门控--allow-writes/--allow-dangerous-sql机制。读完本文你将能像 AI Agent 一样安全、规范地使用dbx命令完成先探索、后查询、再汇报的完整数据库工作流并理解每条命令背后的安全防线与错误处理方式。背景与前提DBX CLI 是 DBX轻量级跨平台数据库管理工具支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 90 数据库提供的命令行界面专门面向数据库 Schema 探索与只读查询场景是 AI Agent如 Codex、Claude与 DBX 管理的数据库之间的标准操作入口。在开始使用之前需要满足两个前提安装并配置 DBX Desktop桌面端已安装且至少配置好一个数据库连接Connection。安装 CLI通过 npm 全局安装npm install -g dbx-app/cli安装完成后先用dbx doctor验证环境是否就绪详见下文环境自检小节。从源码看npm 包本身是一个平台二进制加载器packages/cli/package.json通过optionalDependencies声明了六个平台专属包dbx-app/cli-darwin-arm64、dbx-app/cli-linux-x64-gnu、dbx-app/cli-win32-x64等bin/dbx.js 会根据process.platform与process.arch解析对应包中的原生二进制并通过spawnSync透传所有参数执行。若使用了--no-optional安装导致平台包缺失启动器会明确提示Reinstall dbx-app/cli without --no-optional。CLI 本体是 Rust 实现入口位于 crates/dbx-cli/src/main.rs统一入口的完整命令清单可从其usage()函数中查看。核心概念DBX CLI 围绕四个核心概念组织全部命令概念说明对应命令Connection在 DBX Desktop 中配置的命名数据库连接如prod、local以名称标识dbx connections listSchema连接内的表与视图集合dbx schema listQuery针对连接执行的只读 SQL由--allow-writes与--allow-dangerous-sql双重门控dbx queryContext为 AI 提示词优化的精简 Schema 转储比完整 Schema 输出更小、更聚焦dbx context四个概念之间的层级关系如下DBX Desktop ├── Connection (named) │ ├── Schema (tables, views) │ │ └── Table │ │ └── Column (name, type, nullable, default) │ └── Query (read-only by default) └── Context (prompt-optimized schema dump)从源码结构看crates/dbx-cli/src/main.rs中的Flags结构体第 88-106 行完整定义了 CLI 支持的参数--json/--format输出格式、--schema/--database范围限定、--tables/--max-tables表过滤、--limit/--timeout查询限制、--fileSQL 文件、--out/--notes文档导出、--allow-writes/--allow-dangerous-sql写操作开关等与本文将要讲解的各命令一一对应。环境自检与能力探测在任何数据库操作之前Agent 应当先确认环境状态# 检查桌面端桥接、连接数据库与原生 SQLite 加载器是否可用 dbx doctor # 查看哪些数据库类型支持直连执行哪些必须走桌面桥接 dbx capabilitiesdoctor在 Agent 启动时或某条命令失败时使用。它会输出一系列诊断信息包括应用数据目录、DBX 数据库文件是否存在、连接表行数、连接加载是否成功、桌面桥接端口文件是否存在等。从源码看diagnostics()函数crates/dbx-cli/src/main.rs#L869-L908会检查app_data_dir下的存储数据库文件与mcp-bridge-port端口文件后者存在则拼出http://127.0.0.1:port形式的桥接地址用于判断桌面桥接是否在运行。capabilities输出两种模式的数据库类型清单——Direct直连与Requires DBX Desktop需桥接帮助 Agent 判断哪些命令可以在无桌面端环境下执行。源码中的两个常量表crates/dbx-cli/src/main.rs#L18-L79定义了完整分类详情见下文直接执行与桥接执行小节。连接管理# 列出所有已配置的连接不泄露任何密钥 dbx connections list --json务必在任何 Schema 或查询操作之前先执行此命令——用户可能记不清连接的确切名称。该命令返回 JSON 格式的连接列表名称、类型、主机、端口、数据库但不包含密码等机密信息。从源码的format_connections函数crates/dbx-cli/src/main.rs#L723-L748可以看出输出字段固定为name、type、host、port、database不含任何凭据字段。Agent 应将 JSON 解析后以整洁的列表呈现给用户而不要直接展示原始 JSON 或凭据信息。Schema 探索# 列出某个连接中的所有表 dbx schema list connection --json # 描述某张具体表的结构 dbx schema describe connection table --json标准探索策略是先用schema list整体扫描可用表再用schema describe深入用户关注的具体表最后清晰地向用户呈现列名、类型与可空性nullability。从源码实现看schema list会调用后端list_tables输出每个表的name与typecrates/dbx-cli/src/main.rs#L750-L769schema describe调用get_columns输出列的name、data_type、is_nullable、is_primary_key、column_default、comment等完整元数据crates/dbx-cli/src/main.rs#L771-L801Markdown 表格模式下主键列会以(PK)后缀标注便于人读。两个命令均支持--schema name指定 Schema、--database name覆盖连接的默认数据库selected_database函数的解析逻辑见 crates/dbx-cli/src/main.rs#L577-L579。连接名匹配不区分大小写find_connection使用eq_ignore_ascii_case。查询执行与安全门控基本用法# 只读查询默认行为 dbx query connection SELECT ... --json # 从 SQL 文件执行 dbx query connection --file ./query.sql --json # 限制行数与超时时间 dbx query connection SELECT ... --limit 50 --timeout 10s --json以--分隔以支持以短横线开头的 SQL如果 SQL 以短横线开头例如以--注释开头需用--显式分隔参数dbx query local --json -- -- comment select 1写操作的安全门控CRITICAL默认只读这是本 CLI 最核心的安全设计。写操作INSERT / UPDATE / DELETE必须显式添加--allow-writes危险 SQLDROP / TRUNCATE / ALTER必须同时添加--allow-writes和--allow-dangerous-sql除非用户明确确认某个写操作绝不自行添加这些开关。源码中的强制校验逻辑位于run_querycrates/dbx-cli/src/main.rs#L292-L386--allow-dangerous-sql单独出现未带--allow-writes且环境变量也未放行会直接返回INVALID_OPTIONSQL 会经classify_sql_risk_for_database分类为ReadOnly、Write、Ddl、Transaction等风险等级Write风险但未开--allow-writes或Ddl风险但未开--allow-dangerous-sql一律返回SQL_BLOCKED非只读语句若命中生产库保护targets_production_database实现在 crates/dbx-core/src/safety/production_safety.rs同样被SQL_BLOCKED拦截。生产库保护还具备跨库识别能力即使当前选中库是 staging只要 SQL 中显式引用了标记为生产的库如DELETE FROM prod_app.users、USE prod_app; ...、COPY prod_app.users FROM ...、CALL prod_app.purge_users()也会被拦截——相关测试用例crates/dbx-core/src/safety/production_safety.rs#L832-L860覆盖了这些跨库写场景。此外环境变量DBX_MCP_ALLOW_WRITES/DBX_MCP_ALLOW_DANGEROUS_SQL取值为1或true可以作为全局放行开关源码见env_flag与 crates/dbx-cli/src/main.rs#L325-L331。特殊数据库类型的处理Redis不接受 SQLdbx query对 Redis 连接直接返回REDIS_COMMAND_REQUIRED应改用 MCP Redis 命令工具或 DBX 桌面端crates/dbx-cli/src/main.rs#L333-L337MongoDB走独立的命令解析与安全校验mongo::parsemongo::validate_safety写命令需--allow-writesupdate/delete 要求非空过滤条件危险命令需--allow-dangerous-sql生产库写操作一律拦截crates/dbx-cli/src/main.rs#L339-L368。参数细节--timeout支持ms、s、m三种后缀如500ms、10s、1m不带后缀默认为毫秒--limit必须是正整数。非法值会返回INVALID_OPTION。解析实现见 crates/dbx-cli/src/main.rs#L662-L688。生成 AI 提示词上下文当用户想写查询但需要先了解 Schema 时使用context命令生成面向提示词的紧凑 Schema 转储# 完整 Schema 上下文 dbx context connection # 只包含指定表 dbx context connection --tables users,orders,products设计意图context的输出专门为 AI 提示词优化比完整 Schema 输出更小、更聚焦可直接管道pipe进提示词。推荐使用--tables限定范围以节省 token。从源码的run_contextcrates/dbx-cli/src/main.rs#L396-L470可以看到更多可调参数--max-tables n默认只取前 8 张表取值范围被钳制在 120--tables过滤是大小写不敏感的且只匹配明确指定的表名若结果被截断输出末尾会附加提示Note: table list was truncated; request specific table names for more context.默认非 JSON输出采用类 Markdown 结构## 表名、Type: ...、每列一行- 列名 类型 NULL/NOT NULL [PK] [-- 注释]这种结构对 LLM 解析非常友好--schema、--database同样适用--format csv不受支持返回INVALID_OPTION因为上下文本身是结构化的 Schema 快照。默认连接环境变量设置DBX_CONNECTION后可省略 query/context 命令中的连接参数export DBX_CONNECTIONprod dbx query SELECT 1 --json dbx context --tables usersAgent 应检测环境中是否设置了该变量并优先使用。源码在run_query与run_context中均实现了该逻辑当DBX_CONNECTION非空且参数个数符合省略形态时自动注入默认连接名crates/dbx-cli/src/main.rs#L294-L315。注意dbx query场景下如果同时提供了--file与内联 SQL会返回INVALID_ARGUMENTProvide SQL either inline or with --file, not both。输出格式Flag适用场景--json机器可读、可自动解析Agent 应始终使用--format csv管道传给其他 CLI 工具补充说明--format还支持table默认值Markdown 风格表格三者通过parse_flags统一解析crates/dbx-cli/src/main.rs#L607-L617错误输出约定所有错误都写入 stderr并以非零退出码结束使用--json时错误以{error: {code: ..., message: ...}}的结构化 JSON 输出crates/dbx-cli/src/main.rs#L165-L177任何命令意外失败时先运行dbx doctor排查环境问题。错误码速查表Code含义Agent 应采取的响应CONNECTION_NOT_FOUND连接名不存在用dbx connections list --json列出可用连接SQL_BLOCKED未加--allow-writes就尝试写操作询问用户这是写操作是否确认绝不自动添加写开关DBX_NOT_RUNNING桌面端桥接不可用提示用户打开 DBX Desktop用dbx capabilities确认哪些命令无需桥接即可执行INVALID_OPTION参数或取值错误查看dbx --help后重试ERROR意外的运行时故障运行dbx doctor、检查日志、重试一次除表中条目外源码中还存在INVALID_ARGUMENT参数数量不匹配、UNKNOWN_OPTION未知选项、CONNECTION_STORE_ERROR连接存储不可用等补充错误码以及上文提到的REDIS_COMMAND_REQUIRED。错误码通过CliError结构体crates/dbx-cli/src/main.rs#L108-L118统一构造全部遵循stderr 非零退出码的约定。直接执行与桥接执行不同数据库类型走两种不同的执行路径直连执行无需 DBX DesktopPostgreSQL、Redshift、MySQL及兼容的 Doris、StarRocks、ManticoreSearch、SQLite及 rqlite、kwdb、QuestDB。源码中的DIRECT_QUERY_TYPES常量为postgres, redshift, mysql, doris, starrocks, manticoresearch, sqlite, rqlite, kwdb, questdbcrates/dbx-cli/src/main.rs#L18-L19桥接执行需要 DBX Desktop 运行其余类型均要求桌面桥接包括 Redis、MongoDB、DuckDB、ClickHouse、SQL Server、Oracle、Elasticsearch、达梦dameng、人大金仓kingbase、GaussDB、Snowflake、Trino、Hive、Spark、DB2、Informix、Neo4j、Cassandra、BigQuery、Spanner、OceanBase(Oracle 模式)、TDengine、IoTDB、H2、InfluxDB、ZooKeeper 等完整清单见 crates/dbx-cli/src/main.rs#L20-L79 的BRIDGE_REQUIRED_TYPES。用dbx capabilities确认某类型属于哪种模式。对桥接模式而言dbx open connection table可以直接在 DBX Desktop 中打开指定表需要桥接失败时报DBX_NOT_RUNNINGcrates/dbx-cli/src/main.rs#L259-L288。常见陷阱与规避连接名写错—— 在运行任何 Schema 或查询命令之前先用dbx connections list --json列出连接绝不从对话上下文臆测连接名。上下文污染导致 Schema 混淆—— 用户提到某张表时先确认连接与表确实存在dbx schema list conn --json就是验证步骤不要拿记忆或猜测代替。误触发写操作—— 除非用户明确确认绝不添加--allow-writes或--allow-dangerous-sql拿不准就询问用户。桌面桥接缺失—— 若dbx open或桥接类连接失败运行dbx doctor并提示用户打开 DBX Desktop。无需桥接即可执行的命令connections list、schema list、schema describe、query、context针对 PostgreSQL/MySQL/SQLite。大查询超时—— 探索性查询始终加--limit 50 --timeout 10s仅当用户明确要求全量结果时才放宽或移除限制。JSON 解析失败—— 旧版 DBX 可能不支持部分命令的--json若 JSON 输出异常去掉--json改用人类可读输出再解析。此外还有一个容易被忽略的原则文档中特别强调任何情况下都不要绕过 CLI 访问数据库。如果dbx返回SQL_BLOCKED或其他错误绝不使用 Python sqlite3、shell 重定向等工具直接访问数据库——必须尊重 CLI 的安全门控向用户如实转述 CLI 的返回结果并征求其决策。多步工作流实战工作流一先探索后查询dbx connections list --json—— 确认连接存在dbx schema list conn --json—— 扫描可用表dbx schema describe conn table --json—— 理解目标表结构dbx query conn SELECT ... --limit 50 --timeout 10s --json—— 执行只读查询向用户呈现结果并附上行数工作流二生成上下文后协助编写查询dbx context conn --tables a,b—— 获取紧凑 Schema阅读输出、理解表间关系起草 SQL 并展示给用户评审用户确认后执行dbx query conn polished sql --json工作流三跨连接对比dbx connections list --json—— 确定源与目标连接dbx schema describe source_conn table --json—— 获取源表结构dbx schema describe target_conn table --json—— 获取目标表结构对比并汇报差异延伸阅读想深入了解本文涉及的实现细节可以在当前仓库中继续阅读CLI 入口与全部命令解析crates/dbx-cli/src/main.rsnpm 发布包与平台二进制加载器packages/cli/package.json、packages/cli/bin/dbx.jsSQL 风险分级与生产库保护crates/dbx-core/src/safety/production_safety.rs、crates/dbx-sql/src/sql_risk.rs连接模型is_production/production_databases等字段的定义与含义crates/dbx-core/src/models/connection.rsAgent 技能原文档skills/dbx/SKILL.md【免费下载链接】dbx25 MB lightweight cross-platform database client for 90 databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 90 数据库提供桌面端、Docker、CLI、内置 AI 助手和 MCP Server。项目地址: https://gitcode.com/gh_mirrors/dbx7/dbx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/21 2:24:56 · 阅读 1.2k DBX CLI 数据库安全查询与 Schema 探索指南：面向 AI Agent 的命令行操作手册
DBX CLI 数据库安全查询与 Schema 探索指南面向 AI Agent 的命令行操作手册【免费下载链接】dbx25 MB lightweight cross-platform database client for 90 databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 90 数据库提供桌面端、Docker、CLI、内置 AI 助手和 MCP Server。项目地址: https://gitcode.com/gh_mirrors/dbx7/dbx本文以skills/dbx/SKILL.md为骨架结合仓库中crates/dbx-cli、crates/dbx-core等源码实现系统讲解 DBX CLI 的安装验证、连接管理、Schema 探索、只读查询、AI 提示词上下文生成以及贯穿始终的安全门控--allow-writes/--allow-dangerous-sql机制。读完本文你将能像 AI Agent 一样安全、规范地使用dbx命令完成先探索、后查询、再汇报的完整数据库工作流并理解每条命令背后的安全防线与错误处理方式。背景与前提DBX CLI 是 DBX轻量级跨平台数据库管理工具支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 90 数据库提供的命令行界面专门面向数据库 Schema 探索与只读查询场景是 AI Agent如 Codex、Claude与 DBX 管理的数据库之间的标准操作入口。在开始使用之前需要满足两个前提安装并配置 DBX Desktop桌面端已安装且至少配置好一个数据库连接Connection。安装 CLI通过 npm 全局安装npm install -g dbx-app/cli安装完成后先用dbx doctor验证环境是否就绪详见下文环境自检小节。从源码看npm 包本身是一个平台二进制加载器packages/cli/package.json通过optionalDependencies声明了六个平台专属包dbx-app/cli-darwin-arm64、dbx-app/cli-linux-x64-gnu、dbx-app/cli-win32-x64等bin/dbx.js 会根据process.platform与process.arch解析对应包中的原生二进制并通过spawnSync透传所有参数执行。若使用了--no-optional安装导致平台包缺失启动器会明确提示Reinstall dbx-app/cli without --no-optional。CLI 本体是 Rust 实现入口位于 crates/dbx-cli/src/main.rs统一入口的完整命令清单可从其usage()函数中查看。核心概念DBX CLI 围绕四个核心概念组织全部命令概念说明对应命令Connection在 DBX Desktop 中配置的命名数据库连接如prod、local以名称标识dbx connections listSchema连接内的表与视图集合dbx schema listQuery针对连接执行的只读 SQL由--allow-writes与--allow-dangerous-sql双重门控dbx queryContext为 AI 提示词优化的精简 Schema 转储比完整 Schema 输出更小、更聚焦dbx context四个概念之间的层级关系如下DBX Desktop ├── Connection (named) │ ├── Schema (tables, views) │ │ └── Table │ │ └── Column (name, type, nullable, default) │ └── Query (read-only by default) └── Context (prompt-optimized schema dump)从源码结构看crates/dbx-cli/src/main.rs中的Flags结构体第 88-106 行完整定义了 CLI 支持的参数--json/--format输出格式、--schema/--database范围限定、--tables/--max-tables表过滤、--limit/--timeout查询限制、--fileSQL 文件、--out/--notes文档导出、--allow-writes/--allow-dangerous-sql写操作开关等与本文将要讲解的各命令一一对应。环境自检与能力探测在任何数据库操作之前Agent 应当先确认环境状态# 检查桌面端桥接、连接数据库与原生 SQLite 加载器是否可用 dbx doctor # 查看哪些数据库类型支持直连执行哪些必须走桌面桥接 dbx capabilitiesdoctor在 Agent 启动时或某条命令失败时使用。它会输出一系列诊断信息包括应用数据目录、DBX 数据库文件是否存在、连接表行数、连接加载是否成功、桌面桥接端口文件是否存在等。从源码看diagnostics()函数crates/dbx-cli/src/main.rs#L869-L908会检查app_data_dir下的存储数据库文件与mcp-bridge-port端口文件后者存在则拼出http://127.0.0.1:port形式的桥接地址用于判断桌面桥接是否在运行。capabilities输出两种模式的数据库类型清单——Direct直连与Requires DBX Desktop需桥接帮助 Agent 判断哪些命令可以在无桌面端环境下执行。源码中的两个常量表crates/dbx-cli/src/main.rs#L18-L79定义了完整分类详情见下文直接执行与桥接执行小节。连接管理# 列出所有已配置的连接不泄露任何密钥 dbx connections list --json务必在任何 Schema 或查询操作之前先执行此命令——用户可能记不清连接的确切名称。该命令返回 JSON 格式的连接列表名称、类型、主机、端口、数据库但不包含密码等机密信息。从源码的format_connections函数crates/dbx-cli/src/main.rs#L723-L748可以看出输出字段固定为name、type、host、port、database不含任何凭据字段。Agent 应将 JSON 解析后以整洁的列表呈现给用户而不要直接展示原始 JSON 或凭据信息。Schema 探索# 列出某个连接中的所有表 dbx schema list connection --json # 描述某张具体表的结构 dbx schema describe connection table --json标准探索策略是先用schema list整体扫描可用表再用schema describe深入用户关注的具体表最后清晰地向用户呈现列名、类型与可空性nullability。从源码实现看schema list会调用后端list_tables输出每个表的name与typecrates/dbx-cli/src/main.rs#L750-L769schema describe调用get_columns输出列的name、data_type、is_nullable、is_primary_key、column_default、comment等完整元数据crates/dbx-cli/src/main.rs#L771-L801Markdown 表格模式下主键列会以(PK)后缀标注便于人读。两个命令均支持--schema name指定 Schema、--database name覆盖连接的默认数据库selected_database函数的解析逻辑见 crates/dbx-cli/src/main.rs#L577-L579。连接名匹配不区分大小写find_connection使用eq_ignore_ascii_case。查询执行与安全门控基本用法# 只读查询默认行为 dbx query connection SELECT ... --json # 从 SQL 文件执行 dbx query connection --file ./query.sql --json # 限制行数与超时时间 dbx query connection SELECT ... --limit 50 --timeout 10s --json以--分隔以支持以短横线开头的 SQL如果 SQL 以短横线开头例如以--注释开头需用--显式分隔参数dbx query local --json -- -- comment select 1写操作的安全门控CRITICAL默认只读这是本 CLI 最核心的安全设计。写操作INSERT / UPDATE / DELETE必须显式添加--allow-writes危险 SQLDROP / TRUNCATE / ALTER必须同时添加--allow-writes和--allow-dangerous-sql除非用户明确确认某个写操作绝不自行添加这些开关。源码中的强制校验逻辑位于run_querycrates/dbx-cli/src/main.rs#L292-L386--allow-dangerous-sql单独出现未带--allow-writes且环境变量也未放行会直接返回INVALID_OPTIONSQL 会经classify_sql_risk_for_database分类为ReadOnly、Write、Ddl、Transaction等风险等级Write风险但未开--allow-writes或Ddl风险但未开--allow-dangerous-sql一律返回SQL_BLOCKED非只读语句若命中生产库保护targets_production_database实现在 crates/dbx-core/src/safety/production_safety.rs同样被SQL_BLOCKED拦截。生产库保护还具备跨库识别能力即使当前选中库是 staging只要 SQL 中显式引用了标记为生产的库如DELETE FROM prod_app.users、USE prod_app; ...、COPY prod_app.users FROM ...、CALL prod_app.purge_users()也会被拦截——相关测试用例crates/dbx-core/src/safety/production_safety.rs#L832-L860覆盖了这些跨库写场景。此外环境变量DBX_MCP_ALLOW_WRITES/DBX_MCP_ALLOW_DANGEROUS_SQL取值为1或true可以作为全局放行开关源码见env_flag与 crates/dbx-cli/src/main.rs#L325-L331。特殊数据库类型的处理Redis不接受 SQLdbx query对 Redis 连接直接返回REDIS_COMMAND_REQUIRED应改用 MCP Redis 命令工具或 DBX 桌面端crates/dbx-cli/src/main.rs#L333-L337MongoDB走独立的命令解析与安全校验mongo::parsemongo::validate_safety写命令需--allow-writesupdate/delete 要求非空过滤条件危险命令需--allow-dangerous-sql生产库写操作一律拦截crates/dbx-cli/src/main.rs#L339-L368。参数细节--timeout支持ms、s、m三种后缀如500ms、10s、1m不带后缀默认为毫秒--limit必须是正整数。非法值会返回INVALID_OPTION。解析实现见 crates/dbx-cli/src/main.rs#L662-L688。生成 AI 提示词上下文当用户想写查询但需要先了解 Schema 时使用context命令生成面向提示词的紧凑 Schema 转储# 完整 Schema 上下文 dbx context connection # 只包含指定表 dbx context connection --tables users,orders,products设计意图context的输出专门为 AI 提示词优化比完整 Schema 输出更小、更聚焦可直接管道pipe进提示词。推荐使用--tables限定范围以节省 token。从源码的run_contextcrates/dbx-cli/src/main.rs#L396-L470可以看到更多可调参数--max-tables n默认只取前 8 张表取值范围被钳制在 120--tables过滤是大小写不敏感的且只匹配明确指定的表名若结果被截断输出末尾会附加提示Note: table list was truncated; request specific table names for more context.默认非 JSON输出采用类 Markdown 结构## 表名、Type: ...、每列一行- 列名 类型 NULL/NOT NULL [PK] [-- 注释]这种结构对 LLM 解析非常友好--schema、--database同样适用--format csv不受支持返回INVALID_OPTION因为上下文本身是结构化的 Schema 快照。默认连接环境变量设置DBX_CONNECTION后可省略 query/context 命令中的连接参数export DBX_CONNECTIONprod dbx query SELECT 1 --json dbx context --tables usersAgent 应检测环境中是否设置了该变量并优先使用。源码在run_query与run_context中均实现了该逻辑当DBX_CONNECTION非空且参数个数符合省略形态时自动注入默认连接名crates/dbx-cli/src/main.rs#L294-L315。注意dbx query场景下如果同时提供了--file与内联 SQL会返回INVALID_ARGUMENTProvide SQL either inline or with --file, not both。输出格式Flag适用场景--json机器可读、可自动解析Agent 应始终使用--format csv管道传给其他 CLI 工具补充说明--format还支持table默认值Markdown 风格表格三者通过parse_flags统一解析crates/dbx-cli/src/main.rs#L607-L617错误输出约定所有错误都写入 stderr并以非零退出码结束使用--json时错误以{error: {code: ..., message: ...}}的结构化 JSON 输出crates/dbx-cli/src/main.rs#L165-L177任何命令意外失败时先运行dbx doctor排查环境问题。错误码速查表Code含义Agent 应采取的响应CONNECTION_NOT_FOUND连接名不存在用dbx connections list --json列出可用连接SQL_BLOCKED未加--allow-writes就尝试写操作询问用户这是写操作是否确认绝不自动添加写开关DBX_NOT_RUNNING桌面端桥接不可用提示用户打开 DBX Desktop用dbx capabilities确认哪些命令无需桥接即可执行INVALID_OPTION参数或取值错误查看dbx --help后重试ERROR意外的运行时故障运行dbx doctor、检查日志、重试一次除表中条目外源码中还存在INVALID_ARGUMENT参数数量不匹配、UNKNOWN_OPTION未知选项、CONNECTION_STORE_ERROR连接存储不可用等补充错误码以及上文提到的REDIS_COMMAND_REQUIRED。错误码通过CliError结构体crates/dbx-cli/src/main.rs#L108-L118统一构造全部遵循stderr 非零退出码的约定。直接执行与桥接执行不同数据库类型走两种不同的执行路径直连执行无需 DBX DesktopPostgreSQL、Redshift、MySQL及兼容的 Doris、StarRocks、ManticoreSearch、SQLite及 rqlite、kwdb、QuestDB。源码中的DIRECT_QUERY_TYPES常量为postgres, redshift, mysql, doris, starrocks, manticoresearch, sqlite, rqlite, kwdb, questdbcrates/dbx-cli/src/main.rs#L18-L19桥接执行需要 DBX Desktop 运行其余类型均要求桌面桥接包括 Redis、MongoDB、DuckDB、ClickHouse、SQL Server、Oracle、Elasticsearch、达梦dameng、人大金仓kingbase、GaussDB、Snowflake、Trino、Hive、Spark、DB2、Informix、Neo4j、Cassandra、BigQuery、Spanner、OceanBase(Oracle 模式)、TDengine、IoTDB、H2、InfluxDB、ZooKeeper 等完整清单见 crates/dbx-cli/src/main.rs#L20-L79 的BRIDGE_REQUIRED_TYPES。用dbx capabilities确认某类型属于哪种模式。对桥接模式而言dbx open connection table可以直接在 DBX Desktop 中打开指定表需要桥接失败时报DBX_NOT_RUNNINGcrates/dbx-cli/src/main.rs#L259-L288。常见陷阱与规避连接名写错—— 在运行任何 Schema 或查询命令之前先用dbx connections list --json列出连接绝不从对话上下文臆测连接名。上下文污染导致 Schema 混淆—— 用户提到某张表时先确认连接与表确实存在dbx schema list conn --json就是验证步骤不要拿记忆或猜测代替。误触发写操作—— 除非用户明确确认绝不添加--allow-writes或--allow-dangerous-sql拿不准就询问用户。桌面桥接缺失—— 若dbx open或桥接类连接失败运行dbx doctor并提示用户打开 DBX Desktop。无需桥接即可执行的命令connections list、schema list、schema describe、query、context针对 PostgreSQL/MySQL/SQLite。大查询超时—— 探索性查询始终加--limit 50 --timeout 10s仅当用户明确要求全量结果时才放宽或移除限制。JSON 解析失败—— 旧版 DBX 可能不支持部分命令的--json若 JSON 输出异常去掉--json改用人类可读输出再解析。此外还有一个容易被忽略的原则文档中特别强调任何情况下都不要绕过 CLI 访问数据库。如果dbx返回SQL_BLOCKED或其他错误绝不使用 Python sqlite3、shell 重定向等工具直接访问数据库——必须尊重 CLI 的安全门控向用户如实转述 CLI 的返回结果并征求其决策。多步工作流实战工作流一先探索后查询dbx connections list --json—— 确认连接存在dbx schema list conn --json—— 扫描可用表dbx schema describe conn table --json—— 理解目标表结构dbx query conn SELECT ... --limit 50 --timeout 10s --json—— 执行只读查询向用户呈现结果并附上行数工作流二生成上下文后协助编写查询dbx context conn --tables a,b—— 获取紧凑 Schema阅读输出、理解表间关系起草 SQL 并展示给用户评审用户确认后执行dbx query conn polished sql --json工作流三跨连接对比dbx connections list --json—— 确定源与目标连接dbx schema describe source_conn table --json—— 获取源表结构dbx schema describe target_conn table --json—— 获取目标表结构对比并汇报差异延伸阅读想深入了解本文涉及的实现细节可以在当前仓库中继续阅读CLI 入口与全部命令解析crates/dbx-cli/src/main.rsnpm 发布包与平台二进制加载器packages/cli/package.json、packages/cli/bin/dbx.jsSQL 风险分级与生产库保护crates/dbx-core/src/safety/production_safety.rs、crates/dbx-sql/src/sql_risk.rs连接模型is_production/production_databases等字段的定义与含义crates/dbx-core/src/models/connection.rsAgent 技能原文档skills/dbx/SKILL.md【免费下载链接】dbx25 MB lightweight cross-platform database client for 90 databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 90 数据库提供桌面端、Docker、CLI、内置 AI 助手和 MCP Server。项目地址: https://gitcode.com/gh_mirrors/dbx7/dbx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考