whodb

WhoDB 数据库助手

你可以使用 WhoDB 执行数据库操作。使用这些工具和命令帮助用户完成数据库任务。

Platform MCP（默认）

whodb mcp serve 会公开托管平台工具。使用 whodb login --host <url> 登录每个所需的主机。先使用 whodb_platform_hosts 发现已保存的 主机和账户，然后使用 whodb_platform_orgs（传入 workspace: {host}）和 whodb_platform_projects（传入 workspace: {host, org}）。

使用 whodb_platform_workspace_resolve 确定目标。在 UAT、生产环境或不同项目中操作时，后续工具调用请传入明确的 workspace: {host, org, project}。目标仅适用于单次调用（包括并行调用）， 不会更改已保存的默认值。检查返回的 scope。不要运行 whodb use 切换其他会话的默认值。未指定目标时，将依次使用进程级覆盖项和已保存的默认值。查看 whodb://platform/schema 了解操作和负载格式。

写入操作会返回绑定到主机、账户、组织和项目的预览。仅在用户批准该预览后确认。 更改默认值不会重定向待确认的操作。主机需要身份验证时，请让用户运行 whodb login --host <url>；每个项目无需单独登录。

引导式设置

此技能为可选项。WhoDB MCP 提供自己的说明、工具架构和设置指引。如果此技能与其内容不同，请优先参考实时 MCP 发现结果。 保留一个条目：命令 whodb，参数 ["mcp", "serve"]。

使用 whodb_mcp_setup 并传入 action: "inspect"，发现设置、目标、选项和设置架构。询问用户的需求，然后使用 action: "preview" 并传入 patch。展示拟议的设置并获得批准后，再使用返回的 confirmation_token 和 approved: true 调用 action: "apply"。 不要在 apply 时发送 patch。令牌五分钟后过期，且仅最新预览有效。设置更改后重启 MCP，然后使用 action: "verify"。 验证会检查当前生效的设置。未提供的 patch 字段会保留原值。

此流程无需访问 shell。浏览器登录和凭据输入由用户自行操作；切勿在聊天中索取凭据。如果设置工具被过滤，请让用户运行 whodb setup。 CLI Agent 也可以使用 whodb setup inspect、validate、apply --yes 和 verify。 查看 whodb://mcp/configuration 了解启用的模块和限制。 平台调用的目标为 workspace；数据库调用的目标为 connection。

仅数据库 MCP

通过 whodb setup 启用数据库模块；两个模块可以在同一个 whodb mcp serve 连接中运行。--database 仍可作为高级进程级覆盖项使用。 此模式直接连接数据库，无需 WhoDB 平台服务；数据库可以是远程数据库。可使用 whodb --tui 启动终端 UI。

数据库工具

配置仅数据库 MCP 后，可直接使用以下工具：

whodb_connections

列出所有可用的数据库连接。

No parameters required.
Returns: List of connection names with type and source (env/saved).

whodb_query

对数据库执行 SQL 查询。

Parameters:
- connection: Connection name (optional if only one connection exists)
- query: SQL query to execute

Example: whodb_query(connection="mydb", query="SELECT * FROM users LIMIT 10")

whodb_schemas

列出数据库中的所有架构。

Parameters:
- connection: Connection name (optional if only one connection exists)
- include_tables: Set true to also return tables within each schema (optional)

Example: whodb_schemas(connection="mydb")
Example: whodb_schemas(connection="mydb", include_tables=true)

whodb_tables

列出架构中的所有表。

Parameters:
- connection: Connection name (optional if only one connection exists)
- schema: Schema name (optional, uses default if not specified)
- include_columns: Set true to also return column details for every table (optional)

Example: whodb_tables(connection="mydb", schema="public")
Example: whodb_tables(connection="mydb", schema="public", include_columns=true)

whodb_columns

描述表中的列。

Parameters:
- connection: Connection name (optional if only one connection exists)
- table: Table name (required)
- schema: Schema name (optional)

Example: whodb_columns(connection="mydb", table="users")

CLI 命令（备用）

如果 MCP 工具不可用，可通过 Bash 直接使用 CLI：

执行查询

whodb query "SELECT * FROM users LIMIT 10" --connection mydb --format json

发现架构

# List schemas
whodb schemas --connection mydb --format json

# List tables
whodb tables --connection mydb --schema public --format json

# Describe columns
whodb columns --connection mydb --table users --format json

连接管理

# List connections
whodb connections list --format json

# Test connection
whodb connections test mydb

# Add new connection (interactive)
whodb connections add --name mydb --type Postgres --host localhost --database mydb

数据导出

# Export to CSV
whodb export --connection mydb --table users --output users.csv

# Export query results
whodb export --connection mydb --query "SELECT * FROM orders" --output orders.xlsx

工作流示例

探索新数据库（高效方式）

1. 列出连接：whodb_connections
2. 一次调用获取表及其列：whodb_tables(connection="name", include_columns=true)
3. 抽样查看数据：whodb_query(connection="name", query="SELECT * FROM users LIMIT 5")

查询结果会在列名旁包含 column_types，因此无需单独调用即可了解数据类型。

探索新数据库（多架构）

1. 列出连接：whodb_connections
2. 获取所有包含表的架构：whodb_schemas(connection="name", include_tables=true)
3. 获取你关注的架构中的列：whodb_tables(connection="name", schema="public", include_columns=true)
4. 查询：whodb_query(connection="name", query="SELECT * FROM users LIMIT 5")

回答数据问题

1. 先了解架构——检查表结构
2. 编写带有适当筛选条件的定向查询
3. 探索性查询始终使用 LIMIT
4. 以清晰易读的格式呈现结果

最佳实践

• 编写查询前始终先探索架构
• 探索性查询使用 LIMIT，避免输出内容过多
• 优先选择具体列，而不是 SELECT *，以提高清晰度
• 通过 whodb_columns 检查外键，了解表之间的关系
• 以编程方式解析输出时使用 JSON 格式（--format json）
• 切勿暴露凭据——使用连接名称，而不是连接字符串