使用 SAP HANA CLI（hana-cli）进行…

当需要从命令行或结合 MCP 操作 SAP HANA（安装连接、查看对象、执行 SQL、管理 HDI、HANA Cloud、导出 CDS/EDMX/OpenAPI 等格式）时使用。

适用场景

解决思路

1. 安装：运行 `npm install -g hana-cli` 全局安装，然后用 `hana-cli version` 验证安装。
2. 首次连接：运行 `hana-cli connect` 进入交互式连接设置；或直接运行 `hana-cli connect -n "hostname:port" -u DBUSER -p PASSWORD --save` 指定连接并保存；HANA Cloud 使用服务键时运行 `hana-cli connectViaServiceKey`。
3. MCP 集成：使用 hana-mcp-server 集成，通过 Claude 的 Model Context Protocol 做自然语言数据库操作；将传统 CLI 命令与对话式查询结合。
4. MCP 固定版本：捆绑的 MCP 配置固定 `hana-mcp-server@0.3.4`；修改该 pin 前先使用 sap-dependency-security，因为该 server 会接收 HANA 租户连接环境变量。
5. MCP 环境变量：在 `~/.zshrc`、`~/.bashrc` 或项目 `.env` 中添加 `export HANA_HOST="your-hana-host.hanacloud.ondemand.com"`、`export HANA_PORT="443"`、`export HANA_USER="DBADMIN"`、`export HANA_PASSWORD="your-password"`、可选 `export HANA_ENCRYPT="true"`（默认 true）、可选 `export HANA_DATABASE=""`（用于 MDC tenant）、可选 `export HANA_CONNECTION_TYPE="single-container"`。
6. MCP 连接类型：选择 `single-container`（默认，标准 HANA 数据库）、`mdc-system`（多租户系统数据库）、`mdc-tenant`（多租户环境中的特定租户）。
7. CLI vs MCP 选择：探索式查询、临时分析、学习数据库结构、快速数据采样用 MCP；自动化脚本/CI/CD、生成 CDS/EDMX/OpenAPI、复杂多步骤工作流用 CLI。
8. MCP 自然语言查询示例：让 MCP 执行“Show me all schemas in this HANA database”“List all tables in the SYSTEM schema”“Describe the structure of the USERS table”“Sample 5 rows from the PRODUCTS table”“How many rows are in the CUSTOMERS table?”“Check the HANA database status”等查询。
9. MCP 可用工具：调用 `list_schemas` 枚举所有 schema；`list_tables` 显示 schema 中的表；`describe_table` 获取表结构和元数据；`query` 从自然语言执行 SQL 查询；`sample_data` 获取样本行；`system_info` 获取数据库状态和性能。
10. MCP + CLI 工作流：先用 MCP 自然语言探索（如“Show me all tables in the PRODUCTS schema”），再用 MCP 理解结构（如“Describe the PRODUCTS.INVENTORY table”），然后用 CLI 精确输出格式：`hana-cli inspectTable -t INVENTORY -s PRODUCTS -o cds`，最后用 CLI 做 HDI 操作：`hana-cli createContainer -c MY_CONTAINER`。
11. 数据库对象检查：使用 `inspectTable`（别名 `it`、`table`）检查表结构；`inspectView` 检查视图定义；`inspectProcedure` 检查存储过程；`inspectFunction` 检查函数定义；`tables` 列出 schema 中所有表；`views` 列出 schema 中所有视图；`procedures` 列出存储过程；`functions` 列出函数。
12. 查询执行：使用 `querySimple`（别名 `qs`）执行 SQL 查询；`callProcedure`（别名 `cp`）执行存储过程；`hdbsql` 直接执行 SQL。
13. HDI 容器管理：使用 `containers`（别名 `cont`）列出 HDI 容器；`createContainer` 创建新容器；`dropContainer` 删除容器；`activateHDI` 启用 HDI 服务；`adminHDI` 管理 HDI 权限。
14. 云与 BTP 操作：使用 `hanaCloudInstances` 列出 HANA Cloud 实例；`hanaCloudStart` 启动云实例；`hanaCloudStop` 停止云实例；`btp` 配置 BTP CLI；`btpInfo` 显示 BTP 目标信息。
15. 输出格式：使用 `--output` 或 `-o` 指定 17+ 种格式之一。`tbl` 人类可读表格（默认）；`json` JSON 数据；`yaml` YAML；`csv` CSV 导出；`excel` Excel 文件；`cds` CAP CDS 定义；`hdbcds` HANA CDS 格式；`hdbtable` HDB Table 定义；`sql` SQL DDL 语句；`edmx` OData EDMX 元数据；`openapi` OpenAPI/Swagger 规范；`graphql` GraphQL schema。
16. 连接配置优先级：按以下顺序搜索凭据：1) 带 `--admin` 标志的 `default-env-admin.json`；2) 通过 `cds bind` 生成的 `.cdsrc-private.json`；3) 含 VCAP_SERVICES 的 `.env` 文件；4) 通过 `--conn` 参数指定的文件；5) 当前或父目录中的 `default-env.json`；6) `~/.hana-cli/default.json`。连接模板见 `templates/default-env.json`。
17. 将表检查并转换为 CDS：先运行 `hana-cli inspectTable -s MYSCHEMA -t MYTABLE` 检查表结构；再运行 `hana-cli inspectTable -s MYSCHEMA -t MYTABLE -o cds` 转换为 CDS 格式。
18. 批量转换 schema 对象：运行 `hana-cli massConvert -s MYSCHEMA` 将 schema 中所有对象转换为 CDS。
19. 执行查询并导出：运行 `hana-cli querySimple -q "SELECT * FROM MYTABLE" -o json` 导出为 JSON；运行 `hana-cli querySimple -q "SELECT * FROM MYTABLE" -o excel -f ./output -n report` 导出为 Excel 文件。
20. 管理 HDI 容器：运行 `hana-cli containers` 列出所有容器；运行 `hana-cli createContainer -c MY_CONTAINER -g MY_GROUP` 创建新容器；运行 `hana-cli createContainerUsers -c MY_CONTAINER` 创建容器用户。
21. UI 命令：许多命令有浏览器 UI 替代，命令后缀为 `UI`，如 `tablesUI` 可视化浏览表、`containersUI` 浏览器管理容器、`massConvertUI` 可视化批量转换、`querySimpleUI` 查询构建器界面、`systemInfoUI` 系统仪表盘。
22. 关键特性：利用多数据库支持（HANA、PostgreSQL、SQLite 后端）、17+ 输出格式转换（含 CDS、EDMX、OpenAPI）、HDI 容器全生命周期管理、SAP BTP CLI 与 HANA Cloud 集成、缺失参数自动交互提示、服务键认证。
23. 详细参考：查阅 `references/command-reference.md`（全部 91 个命令）、`references/connection-security.md`（连接与安全）、`references/hdi-management.md`（HDI 管理）、`references/output-formats.md`（输出格式）、`references/cloud-operations.md`（云操作）、`references/db-inspection.md`（数据库检查）、`references/mass-operations.md`（批量操作）、`references/system-admin.md`（系统管理）、`references/web-ui.md`（Web UI）、`references/troubleshooting.md`（故障排查）、`references/development-environment.md`（开发环境）、`references/abap-programming.md`（ABAP 编程模式）。
24. 连接问题排查：运行 `hana-cli status` 检查当前连接状态；用显式凭据测试 `hana-cli connect -n "host:443" -u USER -p PASS --encrypt true`；使用 SSL 信任库 `hana-cli connect --trustStore /path/to/certificate.pem`。
25. 权限错误排查：运行 `hana-cli privilegeError` 诊断权限错误；运行 `hana-cli inspectUser` 查看当前用户信息。
26. 版本兼容性检查：Node.js 要求 ≥20.19.0；`@sap/cds` 使用 9.4.4；`@sap/cds-dk` 要求 ≥8.9 以支持 `cds bind`。
27. 捆绑资源：使用 `references/command-reference.md`、`references/abap-programming.md`、`references/development-environment.md`、`references/connection-security.md`、`references/troubleshooting.md`；使用模板 `templates/default-env.json`（CAP 风格绑定的本地连接模板）和 `templates/cdsrc-private.json`（CAP 私有配置模板）。

适用边界 · 注意事项

• 不使用 SAP HANA、SAP BTP 或 HANA Cloud 的场景不适用。
• 无法安装 Node.js ≥20.19.0 或无法使用 npm 全局安装 hana-cli 时不适用。
• 不允许通过 CLI/MCP 传递数据库凭据或接收 HANA 租户连接环境变量时不适用。