sap-hana-cli

SAP HANA Developer CLI (hana-cli)

相关技能

• sap-cap-capire：用于 CAP 数据库开发、HDI 容器管理和 CDS 语法比较
• sap-btp-cloud-platform：用于 HANA Cloud 运维、BTP 集成和云实例管理
• sap-abap-cds：用于比较 CAP 与 ABAP 之间的 CDS 语法，或了解 HANA CDS 功能
• sap-datasphere：用于 SAP Datasphere 集成或数据仓库场景
• sap-dependency-security：当项目包含 hana-cli 依赖项时，用于安全升级依赖项、固定 MCP 服务的精确版本、加固 npm 软件包、检查锁定文件并实施冷却策略

面向开发者的 SAP HANA 数据库开发命令行界面，在 VS Code 等非 SAP 工具环境中尤其有用。

仓库：https://github.com/SAP-samples/hana-developer-cli-tool-example npm 软件包：https://www.npmjs.com/package/hana-cli 当前版本：3.202405.1（2024 年 4 月） Node.js 要求：≥20.19.0

---

目录

• 快速入门
• 核心命令类别
• 输出格式
• 连接配置
• 常见工作流
• 捆绑资源

快速入门

安装

# Install globally via npm (recommended)
npm install -g hana-cli

# Verify installation
hana-cli version

首次连接

# Interactive connection setup
hana-cli connect

# Or specify connection directly
hana-cli connect -n "hostname:port" -u DBUSER -p PASSWORD --save

# Using service key (HANA Cloud)
hana-cli connectViaServiceKey

---

MCP 集成（AI 驱动的数据库操作）

概述

hana-mcp-server 集成可通过 Claude 的 Model Context Protocol 实现自然语言数据库操作。结合使用对话式查询和传统 CLI 命令，构建完整的开发工作流。

设置

捆绑的 MCP 配置固定使用 [email protected]。更改此固定版本前，请使用 sap-dependency-security，因为该服务会接收 HANA 租户连接环境变量。

1. 环境变量

必需的配置（添加到 /.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"  # Optional, defaults to true
export HANA_DATABASE=""     # Optional, for MDC tenant
export HANA_CONNECTION_TYPE="single-container"  # Optional

2. 连接类型

• single-container（默认）：标准 HANA 数据库
• mdc-system：多租户系统数据库
• mdc-tenant：多租户环境中的特定租户

何时使用：CLI 与 MCP

场景	推荐工具	原因
探索性查询、临时分析	MCP	使用自然语言，无需语法
自动化脚本、CI/CD 流水线	CLI	可编写脚本，输出一致
了解数据库结构	MCP	通过对话探索
生成 CDS/EDMX/OpenAPI 输出	CLI	支持 17+ 种格式
复杂的多步骤工作流	CLI	精细控制
快速抽样和检查数据	MCP	适合一次性查询，速度更快

自然语言查询示例

架构与表发现

• “显示此 HANA 数据库中的所有架构”
• “列出 SYSTEM 架构中的所有表”
• “MY_APP 架构中有哪些表？”
• “显示 PUBLIC 架构中的所有视图”

表结构与元数据

• “描述 USERS 表的结构”
• “ORDERS 表有哪些列？”
• “显示 MY_TABLE 的数据类型”
• “CUSTOMERS 表的主键是什么？”

数据抽样与检查

• “从 PRODUCTS 表抽取 5 行样本”
• “显示 SALES_DATA 中的前 10 条记录”
• “获取 ORDER_ITEMS 表的样本数据”
• “显示 MY_TABLE 中的几行数据”

查询执行

• “CUSTOMERS 表中有多少行？”
• “显示 ORDERS 的 STATUS 列中的不同值”
• “PRODUCTS 的 PRICE 列最大值是多少？”
• “查找 USERS 中 country 为 'USA' 的所有记录”

系统性能与监控

• “检查 HANA 数据库状态”
• “显示系统性能指标”
• “当前数据库版本是什么？”

可用的 MCP 工具

hana-mcp-server 提供以下 MCP 工具：

• list_schemas：枚举所有架构
• list_tables：显示架构中的表
• describe_table：获取表结构和元数据
• query：根据自然语言执行 SQL 查询
• sample_data：获取示例行
• system_info：数据库状态和性能

示例：MCP + CLI 工作流

# 1. Use MCP to explore (natural language)
"Show me all tables in the PRODUCTS schema"

# 2. Use MCP to understand structure
"Describe the PRODUCTS.INVENTORY table"

# 3. Use CLI for format conversion (precise output)
hana-cli inspectTable -t INVENTORY -s PRODUCTS -o cds

# 4. Use CLI for HDI operations
hana-cli createContainer -c MY_CONTAINER

---

核心命令类别

数据库对象检查

命令	别名	用途
inspectTable	it, table	检查表结构
inspectView	-	检查视图定义
inspectProcedure	-	检查存储过程
inspectFunction	-	检查函数定义
tables	-	列出架构中的所有表
views	-	列出架构中的所有视图
procedures	-	列出存储过程
functions	-	列出函数

查询执行

命令	别名	用途
querySimple	qs	执行 SQL 查询
callProcedure	cp	执行存储过程
hdbsql	-	直接执行 SQL

HDI 容器管理

命令	别名	用途
containers	cont	列出 HDI 容器
createContainer	-	创建新容器
dropContainer	-	删除容器
activateHDI	-	启用 HDI 服务
adminHDI	-	管理 HDI 权限

云与 BTP 操作

命令	别名	用途
hanaCloudInstances	-	列出 HANA Cloud 实例
hanaCloudStart	-	启动云实例
hanaCloudStop	-	停止云实例
btp	-	配置 BTP CLI
btpInfo	-	显示 BTP 目标信息

---

输出格式

--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 架构

---

连接配置

连接凭据按以下优先级顺序查找：

1. default-env-admin.json（使用 --admin 标志时）
2. .cdsrc-private.json（通过 cds bind）
3. 包含 VCAP_SERVICES 的 .env 文件
4. 通过 --conn 参数指定的文件
5. 当前目录或父目录中的 default-env.json
6. ~/.hana-cli/default.json

连接模板请参阅 templates/default-env.json。

---

常见工作流

检查表并转换为 CDS

# Inspect table structure
hana-cli inspectTable -s MYSCHEMA -t MYTABLE

# Convert to CDS format
hana-cli inspectTable -s MYSCHEMA -t MYTABLE -o cds

批量转换架构对象

# Convert all objects in schema to CDS
hana-cli massConvert -s MYSCHEMA

执行查询并导出

# Run query and export to JSON
hana-cli querySimple -q "SELECT * FROM MYTABLE" -o json

# Export to Excel file
hana-cli querySimple -q "SELECT * FROM MYTABLE" -o excel -f ./output -n report

管理 HDI 容器

# List all containers
hana-cli containers

# Create new container
hana-cli createContainer -c MY_CONTAINER -g MY_GROUP

# Create container users
hana-cli createContainerUsers -c MY_CONTAINER

---

UI 命令

许多命令都有基于浏览器的 UI 替代项（后缀为 UI）：

• tablesUI - 以可视化方式浏览表
• containersUI - 在浏览器中管理容器
• massConvertUI - 可视化批量转换
• querySimpleUI - 查询构建器界面
• systemInfoUI - 系统仪表板

---

主要功能

• 多数据库支持：HANA、PostgreSQL、SQLite 后端
• 格式转换：支持 17 种以上输出格式，包括 CDS、EDMX、OpenAPI
• HDI 管理：完整的容器生命周期管理
• 云集成：支持 SAP BTP CLI 和 HANA Cloud
• 交互式提示：自动提示输入缺失的参数
• 服务密钥认证：安全的云认证

---

详细参考资料

如需完整文档：

• 全部 91 条命令：参见 references/command-reference.md
• 连接与安全：参见 references/connection-security.md
• HDI 管理：参见 references/hdi-management.md
• 输出格式：参见 references/output-formats.md
• 云操作：参见 references/cloud-operations.md
• 数据库检查：参见 references/db-inspection.md
• 批量操作：参见 references/mass-operations.md
• 系统管理：参见 references/system-admin.md
• Web UI 界面：参见 references/web-ui.md
• 故障排查指南：参见 references/troubleshooting.md
• 开发环境：参见 references/development-environment.md
• ABAP 编程模式：参见 references/abap-programming.md

---

故障排查

连接问题

# Check current connection status
hana-cli status

# Test with explicit credentials
hana-cli connect -n "host:443" -u USER -p PASS --encrypt true

# Use SSL trust store
hana-cli connect --trustStore /path/to/certificate.pem

权限错误

# Diagnose privilege errors
hana-cli privilegeError

# View current user info
hana-cli inspectUser

版本兼容性

• Node.js：需要 ≥20.19.0
• @sap/cds：使用 9.4.4
• @sap/cds-dk：cds bind 需要 ≥8.9

---

捆绑资源

参考文档

• references/command-reference.md - 包含所有选项的完整命令参考
• references/abap-programming.md - ABAP 专属编程模式
• references/development-environment.md - 开发环境设置与指南
• references/connection-security.md - 安全连接与凭据处理
• references/troubleshooting.md - 常见错误与恢复步骤

模板

• templates/default-env.json - 用于 CAP 风格绑定的本地连接模板
• templates/cdsrc-private.json - CAP 私有配置模板

资源

• GitHub：https://github.com/SAP-samples/hana-developer-cli-tool-example
• 介绍视频：https://youtu.be/dvVQfi9Qgog
• Cloud Shell 演示：https://youtu.be/L7QyVLvAIIQ
• SAP HANA Cloud：https://help.sap.com/docs/hana-cloud
• SAP CAP：https://cap.cloud.sap/docs/

---

最后更新：2025-11-26 | 版本：1.1.0