SAP HANA CLI

Name: SAP HANA CLI
Author: SAP-samples

本地服务

github.com/SAP-samples数据库1148 周前更新

代码仓库

关于 SAP HANA CLI

SAP HANA CLI（hana-cli）是面向开发者的 SAP HANA 命令行工具，可用于本地及云端开发环境，并通过 default-env.json 等配置连接远程 HANA 数据库。它将常用的复杂命令分组简化，并提供 150 余个 MCP 工具。

主要功能

01视图、表等数据库对象的查看与检查
02CDS 与 EDMX 格式的元数据转换
03基于 npm 的全局安装
04多种连接配置解析顺序

适用场景

01在 VSCode 中进行本地 SAP HANA 开发
02在云端 Shell 中连接 SAP HANA Cloud 实例
03将目录元数据转换为 CDS 以用于 CAP 项目

MCP 相关

该工具提供 150 余个 SAP HANA 数据库工具作为 MCP 工具，供 AI 助手调用。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "sap-samples-hana-cli": {
      "command": "npx",
      "args": [
        "-y",
        "hana-cli"
      ]
    }
  }
}

启动命令npx -y hana-cli

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmhana-cli4.202607.1stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

SAP HANA 开发者命令行界面

⚠️ 重要通知 — 重大更新（2026 年 2 月/3 月）

4.x 版本带来了重大变更，包括迁移到 Express 5、重构数据库连接处理方式以及大幅提升性能。虽然我们进行了广泛测试，但请注意，您的特定环境中可能会遇到问题。

如果遇到问题：

报告问题： 请在我们的 GitHub 问题页面提交问题，并详细说明您的环境和遇到的问题。
回退到稳定版本： 如果您需要快速回退到这些重大变更之前的最后一个稳定版本，可以安装 3.202601.0 版（2026 年 1 月）：
```
npm install -g [email protected]
```

变更内容： 变更日志介绍了所有值得关注的变更，包括迁移到 Express 5、重构数据库连接、优化 CLI 启动性能（快 60-77%）、扩大测试覆盖率（覆盖率超过 85%）以及新增 VitePress 文档站点。

📚 文档

完整文档位于 docs/ 文件夹中，并使用 VitePress 组织。本 README 将提供概览和最重要文档章节的快捷链接。随着项目发展，预计会逐步在 docs 文件夹中添加越来越多的详细文档。

快速链接：

入门指南 - 安装和设置
命令参考 - 所有 20 多个命令及示例
功能指南 - CLI、API、MCP 等
API 参考 - REST API 文档
常见问题 - 常见问题解答
故障排除 - 常见问题及解决方案

在本地运行文档

cd docs
npm install
npm run docs:dev
# Open http://localhost:5173

构建生产版本

cd docs
npm run docs:build
npm run docs:serve

有关完整的文档设置详情，请参阅 docs/README.md。

描述

此示例旨在展示如何构建以开发者为中心的 SAP HANA 命令行工具，特别适用于使用非 SAP 工具（如 VSCode）进行本地 SAP HANA 开发的场景。它使用 default-env.json，该文件常用于本地开发，以连接远程 SAP HANA 数据库（当然，也可以连接本地 SAP HANA express edition 实例）。本示例无意取代 hdbsql 工具，成为通用 SQL 控制台，而是专注于简化并整合常见且复杂的命令；否则，这些命令可能需要通过许多独立脚本来执行。

介绍视频：https://youtu.be/dvVQfi9Qgog

不过，该工具并不限于本地开发，在云端开发时也同样适用。hana-cli 工具也可以在 SAP Business Application Studio、Google Cloud Shell、AWS Cloud9 等环境的云 Shell 中顺畅运行。它也可以连接 SAP BTP 的 SAP HANA 服务或 SAP HANA Cloud 实例。这说明，只要能使用可访问 Node.js 运行时的命令行，几乎任何地方都能运行该工具。即使远程 HANA 实例与我们进行开发任务的云环境不同，我们也可以连接到它。

支持的环境

graph TD
    A["SAP HANA CLI Tool"] --> B{Development Environment}
    B --> C["Local Development"]
    B --> D["Cloud Development"]
    
    C --> C1["VSCode"]
    C --> C2["Local SAP HANA Express"]
    C --> C3["Remote SAP HANA"]
    
    D --> D1["SAP Business App Studio"]
    D --> D2["Google Cloud Shell"]
    D --> D3["AWS Cloud9"]
    D --> D4["SAP BTP HANA Service"]
    D --> D5["SAP HANA Cloud"]
    
    style A fill:#0070C0
    style B fill:#FF6B6B
    style C fill:#51CF66
    style D fill:#FFD93D

在云 Shell 中运行的视频：https://youtu.be/L7QyVLvAIIQ

要求 / 下载和安装

如果您想直接使用该工具，现在也可以从 npm 获取。您可以通过以下方式安装：

npm install -g hana-cli

安装方法

graph LR
    A["SAP HANA CLI Tool"] --> B{Installation Method}
    
    B --> B1["NPM Package<br/>Quick Install"]
    B1 --> B1a["npm install -g hana-cli"]
    B1a --> B1b["✅ Ready to Use"]
    
    B --> B2["Clone & Build<br/>From Source"]
    B2 --> B2a["Clone Repository<br/>from GitHub"]
    B2a --> B2b["Run npm install"]
    B2b --> B2c["Run npm link"]
    B2c --> B2d["✅ Ready to Use"]
    
    style B1 fill:#0070C0,color:#fff
    style B2 fill:#FF6B6B,color:#fff
    style B1b fill:#51CF66,color:#fff
    style B2d fill:#51CF66,color:#fff

除此之外，你也可以按照以下说明从源代码运行：

在开发计算机上安装 Node.js https://nodejs.org/en/download/。需要 22 或更高版本；强烈建议使用 Node.js 24（LTS），遵循 SAP CAP 10 的建议。
从 https://github.com/SAP-samples/hana-developer-cli-tool-example 克隆仓库

git clone https://github.com/SAP-samples/hana-developer-cli-tool-example

在刚刚克隆的 hana-developer-cli-tool-example 项目根目录运行 NPM install，以下载依赖项

npm install

在克隆的项目根目录运行 NPM link，以便在任何位置都能使用 hana-cli 命令 https://docs.npmjs.com/cli/link

npm link

BTP CLI 安装

hana-cli 工具包含多个可与 SAP Business Technology Platform（BTP）服务交互的命令。此工具中所有与 BTP 相关的功能都依赖于已安装且可在系统 PATH 中使用的 SAP BTP Command Line Interface（btp CLI）。

关于 BTP CLI

btp CLI 是 SAP 官方提供的命令行工具，用于管理 SAP Business Technology Platform 上的资源和服务。它提供管理全局账户、目录、子账户、授权、服务实例等功能。hana-cli 工具封装并扩展了其中许多功能，提供便于开发者使用的命令。

使用 install-btp.sh 安装 BTP CLI

对于 Linux 和 macOS 用户，此仓库包含便捷的安装脚本 install-btp.sh，可自动安装 BTP CLI。

此脚本会执行以下操作：

从 SAP Development Tools 下载页面下载最新的 BTP CLI 安装程序
将安装程序设为可执行文件，并在自动确认后运行
配置 shell 别名，以便更轻松地使用 BTP CLI
将 BTP CLI 二进制文件的位置添加到 PATH

使用安装脚本：

chmod +x scripts/install-btp.sh
./scripts/install-btp.sh

运行脚本后，你可能需要重启终端，或运行 source ~/.bashrc 以应用 PATH 更改。

注意： Windows 用户应从 SAP Development Tools 页面下载 BTP CLI，并按照其中针对相应平台的说明进行操作。

验证安装

安装后，你可以运行以下命令，验证 BTP CLI 是否可用：

btp --version

你也可以使用 hana-cli 工具本身检查 BTP CLI 配置：

hana-cli btp

如果已配置，此命令将显示当前 BTP 目标信息，包括全局账户、目录和子账户。

安全

此应用主要使用 default-env.json，该文件通常用于本地开发，以连接远程 HANA DB（当然，也可以用于本地 SAP HANA, express edition 实例）。有关 default-env.json 工作方式的更多详情，请参阅 @sap/xsenv 包或 @sap/hdi-deploy 包的 readme.md。

连接配置解析顺序

不过，该工具不会只在当前目录中查找 default-env.json 文件。它会通过多种选项和路径查找连接参数。检查顺序如下：

graph TD
    A["Connection Resolution<br/>Started"] --> B{Admin Mode<br/>Enabled?}
    B -->|YES| B1["Look for<br/>default-env-admin.json"]
    B -->|NO| C{.cdsrc-private.json<br/>Found?}
    
    B1 --> B2{Found?}
    B2 -->|YES| Z1["Use Admin Credentials"]
    B2 -->|NO| C
    
    C -->|YES| C1["Use CAP cds bind<br/>Dynamic Lookup"]
    C -->|NO| D{.env File<br/>Found?}
    
    C1 --> Z2["Secure Lookup<br/>from CF/K8s"]
    
    D -->|YES| D1{Contains<br/>VCAP_SERVICES?}
    D1 -->|YES| Z3["Use VCAP Services"]
    D1 -->|NO| E
    D -->|NO| E
    
    E{--conn Parameter<br/>Specified?} -->|YES| E1["Look for specified<br/>connection file"]
    E1 --> E2{Local or<br/>Home Found?}
    E2 -->|YES| Z4["Use Specified File"]
    E2 -->|NO| F
    E -->|NO| F
    
    F["Look for<br/>default-env.json<br/>in current/parent dirs"]
    F --> G{Found?}
    G -->|YES| Z5["Use default-env.json"]
    G -->|NO| H["Last Resort:<br/>Look for default.json<br/>in HOME/.hana-cli/"]
    
    H --> I{Found?}
    I -->|YES| Z6["Use default.json"]
    I -->|NO| Z7["❌ No Connection<br/>Configuration Found"]
    
    style Z1 fill:#51CF66
    style Z2 fill:#51CF66
    style Z3 fill:#51CF66
    style Z4 fill:#51CF66
    style Z5 fill:#51CF66
    style Z6 fill:#51CF66
    style Z7 fill:#FF6B6B

首先查找 Admin 选项，并使用 default-env-admin.json——它会覆盖所有其他参数
如果没有 Admin 选项，或者指定了 Admin 选项但在此目录或 5 个父目录中找不到 default-env-admin.json，则查找此目录或 5 个父目录中的 .cdsrc-private.json，并使用 cds bind 功能安全地查找凭据。这是最安全的选项，但请注意：由于凭据不再存储在本地，而是在每次执行命令时动态从 cf 或 k8s 中查找，因此每条命令都会多花几秒钟
如果在此目录或 5 个父目录中找不到 .cdsrc-private.json，则查找此目录或最多 5 个父目录中的 .env 文件
如果找不到 .env 文件，或文件中不包含 VCAP_SERVICES 部分，则检查是否指定了 --conn 参数。如果指定了，则在当前目录或最多 5 个父目录中查找该文件
如果在本地找不到通过 --conn 参数指定的文件，则在 ${homedir}/.hana-cli/ 文件夹中查找
如果没有找到特定的配置文件，则在当前目录或最多 5 个父目录中查找名为 default-env.json 的文件
最后的办法：如果截至此处仍未找到任何文件，则在 ${homedir}/.hana-cli/ 文件夹中查找名为 default.json 的文件

示例

该工具的许多功能都围绕着 HANA 数据库开发中的常见任务。例如，你可能想要获取当前架构／容器中的所有视图列表：

C:\github\hana-xsa-opensap-hana7\user_db>hana-cli views
Schema: OPENSAP_HANA_USER, View: *
SCHEMA_NAME        VIEW_NAME                                    VIEW_OID  COMMENTS
-----------------  -------------------------------------------  --------  ------------
OPENSAP_HANA_USER  user.models::USER_DETAILS                    171133    USER_DETAILS
OPENSAP_HANA_USER  user.models::USER_DETAILS/hier/USER_DETAILS  171139    null

然后，你可能想要检查某个视图，查看其中的列及其数据类型：

C:\github\hana-xsa-opensap-hana7\user_db>hana-cli view * user.models::USER_DETAILS
Schema: %, View: user.models::USER_DETAILS
{ SCHEMA_NAME: 'OPENSAP_HANA_USER',
  VIEW_NAME: 'user.models::USER_DETAILS',
  VIEW_OID: 171133,
  COMMENTS: 'USER_DETAILS',
  IS_COLUMN_VIEW: 'TRUE',
  VIEW_TYPE: 'CALC',
  HAS_STRUCTURED_PRIVILEGE_CHECK: 'TRUE',
  HAS_PARAMETERS: 'TRUE',
  HAS_CACHE: 'NONE',
  CREATE_TIME: '2019-07-30 13:14:15.594000000' }


SCHEMA_NAME        VIEW_NAME                  VIEW_OID  COLUMN_NAME  POSITION  DATA_TYPE_NAME  OFFSET  LENGTH  SCALE  IS_NULLABLE  DEFAULT_VALUE  CS_DATA_TYPE_NAME  COLUMN_ID  COMMENTS
-----------------  -------------------------  --------  -----------  --------  --------------  ------  ------  -----  -----------  -------------  -----------------  ---------  ---------
OPENSAP_HANA_USER  user.models::USER_DETAILS  171133    EMAIL        1         NVARCHAR        0       255     null   TRUE         null           STRING             171135     Email
OPENSAP_HANA_USER  user.models::USER_DETAILS  171133    FIRSTNAME    2         NVARCHAR        0       40      null   TRUE         null           STRING             171136     FirstName
OPENSAP_HANA_USER  user.models::USER_DETAILS  171133    LASTNAME     3         NVARCHAR        0       40      null   TRUE         null           STRING             171137     LastName
OPENSAP_HANA_USER  user.models::USER_DETAILS  171133    USERID       4         INTEGER         0       10      0      TRUE         null           INT                171138     UserId

不过，检查结果有多种输出选项。例如，你正在使用 Cloud Application Programming Model，需要在 CDS 中为某个视图创建代理实体。该工具会读取目录元数据并将其转换为 CDS：

C:\github\hana-xsa-opensap-hana7\user_db>hana-cli view OPENSAP_HANA_USER user.models::USER_DETAILS -o cds
Schema: OPENSAP_HANA_USER, View: user.models::USER_DETAILS
@cds.persistence.exists
Entity user_modelsUSER_DETAILS {
 key    "EMAIL": String(255) null  @title: 'EMAIL: Email' ;
key     "FIRSTNAME": String(40) null  @title: 'FIRSTNAME: FirstName' ;
key     "LASTNAME": String(40) null  @title: 'LASTNAME: LastName' ;
key     "USERID": Integer null  @title: 'USERID: UserId' ;
}

或者，你正在为该视图启用服务，并想查看转换后的 EDMX：

C:\github\hana-xsa-opensap-hana7\user_db>hana-cli view OPENSAP_HANA_USER user.models::USER_DETAILS -o edmx
Schema: OPENSAP_HANA_USER, View: user.models::USER_DETAILS
<?xml version="1.0" encoding="utf-8"?>
<edmx:Edmx Version="1.0" xmlns:edmx="http://schemas.microsoft.com/ado/2007/06/edmx" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns:sap="http://www.sap.com/Protocols/SAPData">
  <edmx:Reference Uri="https://wiki.scn.sap.com/wiki/download/attachments/448470974/Common.xml?api=v2" xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx">
    <edmx:Include Alias="Common" Namespace="com.sap.vocabularies.Common.v1"/>
  </edmx:Reference>
  <edmx:DataServices m:DataServiceVersion="2.0">
    <Schema Namespace="HanaCli" xmlns="http://schemas.microsoft.com/ado/2008/09/edm">
      <EntityContainer Name="EntityContainer" m:IsDefaultEntityContainer="true">
        <EntitySet Name="user_modelsUSER_DETAILS" EntityType="HanaCli.user_modelsUSER_DETAILS"/>
      </EntityContainer>
      <EntityType Name="user_modelsUSER_DETAILS">
        <Key>
          <PropertyRef Name="EMAIL"/>
          <PropertyRef Name="FIRSTNAME"/>
          <PropertyRef Name="LASTNAME"/>
          <PropertyRef Name="USERID"/>
        </Key>
        <Property Name="EMAIL" Type="Edm.String" MaxLength="255"/>
        <Property Name="FIRSTNAME" Type="Edm.String" MaxLength="40"/>
        <Property Name="LASTNAME" Type="Edm.String" MaxLength="40"/>
        <Property Name="USERID" Type="Edm.Int32"/>
      </EntityType>
      <Annotations Target="HanaCli.user_modelsUSER_DETAILS/EMAIL" xmlns="http://docs.oasis-open.org/odata/ns/edm">
        <Annotation Term="Common.Label" String="EMAIL: Email"/>
      </Annotations>
      <Annotations Target="HanaCli.user_modelsUSER_DETAILS/FIRSTNAME" xmlns="http://docs.oasis-open.org/odata/ns/edm">
        <Annotation Term="Common.Label" String="FIRSTNAME: FirstName"/>
      </Annotations>
      <Annotations Target="HanaCli.user_modelsUSER_DETAILS/LASTNAME" xmlns="http://docs.oasis-open.org/odata/ns/edm">
        <Annotation Term="Common.Label" String="LASTNAME: LastName"/>
      </Annotations>
      <Annotations Target="HanaCli.user_modelsUSER_DETAILS/USERID" xmlns="http://docs.oasis-open.org/odata/ns/edm">
        <Annotation Term="Common.Label" String="USERID: UserId"/>
      </Annotations>
    </Schema>
  </edmx:DataServices>
</edmx:Edmx>

该工具甚至可以为任何现有表、视图或 Calculation View 创建临时 OData V4 服务，并在本地启动一个 Fiori Ui 测试界面。 Fioir 示例

项目结构和文档

Utils 文档

对于希望了解或扩展此 CLI 工具所用内部实用工具的开发者，utils/README.md 文件中提供了完整文档。文档涵盖：

核心实用工具：基础模块、连接管理、数据库检查、SQL 注入防护
CLI 集成：BTP、Cloud Foundry 和 XSA CLI 集成实用工具
数据库抽象：通过工厂模式支持多种数据库（HANA、PostgreSQL、SQLite）
使用示例：实用工具模块的实际使用示例

utils 文件夹包含可复用模块，为所有 CLI 命令提供基础，包括数据库连接、终端 UI 组件、安全实用工具和国际化支持。

HTTP 路由文档

hana-cli 工具内置了一个 Web 服务器，可通过 RESTful HTTP 端点提供所有 CLI 功能。所有 HTTP 路由的详细文档请参阅 routes/README.md 文件。该文档涵盖：

基础配置端点：用于管理 CLI 提示词和设置的 GET/PUT 操作
HANA 数据库端点：用于列出和检查 HANA 数据库对象（表、视图、架构、容器等）的完整 API
文档端点：以 HTML 格式访问 README 和 CHANGELOG
WebSocket 支持：为长时间运行的操作提供实时通信
静态资源：UI5 应用程序和 DFA 集成

使用带有 -w 或 --web 标志的某些 CLI 命令时，Web 服务器会自动启动，从而可通过 http://localhost:3010（端口可配置）发送 HTTP 请求来使用所有 hana-cli 功能。

Swagger/OpenAPI 文档

hana-cli Web 服务器现已为所有 REST API 端点提供全面的 Swagger/OpenAPI 3.0 文档。这提供了一个交互式界面，用于浏览和测试所有 HTTP API，便于将 hana-cli 功能集成到你自己的应用程序中。

主要功能：

交互式 API 文档：浏览 27 个以上的文档化端点及完整的请求/响应架构
在线试用功能：直接在浏览器中测试任何 API 端点
自动生成规范：根据路由文件中的 JSDoc 注释自动生成文档
OpenAPI 3.0 标准：业界标准规范，兼容性最佳
分类整理：端点归入 10 个逻辑类别（配置、HANA 系统、HANA 对象、HDI、云服务等）
导出支持：下载原始 OpenAPI JSON 规范，以生成客户端 SDK

访问 Swagger UI：

# Start the UI server
hana-cli ui

# Open browser to Swagger UI
http://localhost:3010/api-docs

# Get raw OpenAPI JSON specification
http://localhost:3010/api-docs.json

有关完整的实现细节、使用示例和自定义选项，请参阅 SWAGGER_IMPLEMENTATION.md 文档。

Web 应用程序（Fiori Launchpad UI）

hana-cli 工具包含一个基于 SAP UI5 和 Fiori Launchpad 构建的完整浏览器界面，为命令行界面提供图形化替代方案。此 Web 界面采用直观的磁贴式导航系统，可用于所有数据库操作。

graph TB
    CLI["hana-cli<br/>Command Line<br/>Interface"]
    
    CLI -->|--web flag| Server["Web Server<br/>Port 3010"]
    
    Server --> UI["Fiori Launchpad UI<br/>SAP UI5 Application"]
    
    UI --> DB["Database<br/>Operations"]
    UI --> Cloud["Cloud Services<br/>BTP/CF Integration"]
    UI --> Admin["Admin<br/>Functions"]
    
    DB --> T["Tables,<br/>Views,<br/>Schemas"]
    DB --> I["Indexes,<br/>Functions,<br/>Procedures"]
    
    Cloud --> HDI["HDI<br/>Containers"]
    Cloud --> SBSS["SBSS<br/>Services"]
    Cloud --> Store["SecureStore<br/>& Schema"]
    
    Admin --> Conv["Mass<br/>Conversion"]
    Admin --> Monitor["System<br/>Monitoring"]
    Admin --> API["REST API"]
    
    API --> Swagger["Swagger/OpenAPI<br/>Documentation<br/>27+ Endpoints"]
    
    style CLI fill:#0070C0,color:#fff
    style Server fill:#FF6B6B,color:#fff
    style UI fill:#FFD93D,color:#000
    style Swagger fill:#51CF66,color:#000

主要功能：

Fiori Launchpad 界面：现代化的响应式 UI，配有整理有序的磁贴组
多个 UI5 应用程序：用于列出、检查和管理数据库对象的专用应用
实时操作：基于 WebSocket 的通信，可实时更新并执行长时间运行的任务
批量转换工具：将表批量转换为 CDS、HDBTable 或 HDBMigrationTable 格式
系统信息仪表板：查看连接详情、版本信息和系统状态
数据库对象浏览器：交互式浏览表、视图、架构、函数、索引等
Cloud Foundry 集成：管理 HDI、SBSS、Schema 和 SecureStore 服务实例
主题支持：自动检测并自定义浅色/深色模式
集成帮助：SAP Digital Foundation Adapter (DFA)，提供情境化帮助

快速开始：

hana-cli tables -w    # Launch web interface with tables view
hana-cli serve        # Start the web server standalone

Web UI 默认运行于 http://localhost:3010，通过易用的图形界面提供所有 CLI 功能。有关所有 Web 应用程序、UI5 组件、配置和开发指南的完整文档，请参阅 app/README.md 文件。

MCP（Model Context Protocol）集成

hana-cli 工具包含一个 Model Context Protocol（MCP）服务，支持 Claude 等 AI 助手通过自然语言与 SAP HANA 数据库交互。该服务采用渐进式发现模型——从约 22 个专用工具开始，并按需扩展至全部 186 条命令。

graph LR
    AI["🤖 AI Assistant<br/>Claude, etc."]

    AI -->|Natural Language<br/>Query| MCP["MCP Server<br/>~22 Default Tools"]

    MCP -->|Router or<br/>Direct Call| Tools["186 hana-cli<br/>Commands"]

    Tools --> DB["SAP HANA<br/>Database"]
    Tools --> Cloud["BTP/Cloud<br/>Services"]
    Tools --> HDI["HDI<br/>Containers"]

    DB -->|Data & Results| Tools
    Cloud -->|Service Info| Tools
    HDI -->|Container Status| Tools

    Tools -->|Formatted<br/>Response| MCP
    MCP -->|Natural Language<br/>Result| AI

    style AI fill:#9D55F0,color:#fff
    style MCP fill:#0070C0,color:#fff
    style Tools fill:#FF6B6B,color:#fff
    style DB fill:#51CF66,color:#fff

主要功能：

渐进式工具发现——始终提供第 1 层工具，其他工具可通过路由器或动态提升获得
路由器工具（hana_execute）可按名称分派任意 183 条以上的命令
AI 指导的命令推荐和智能搜索
与 Claude Desktop、VS Code、Cursor 和其他 MCP 客户端无缝集成
提供 --full 模式，适用于无需顾虑工具数量的环境

如需详细的设置说明、配置选项和使用示例，请参阅：

docs/03-features/mcp-integration.md - 完整的 MCP 概览和设置指南
mcp-server/README.md - 服务安装和配置

标准参数和约定

hana-cli 工具在所有命令中采用一致的参数命名、别名和默认值约定，从而提供可预测且直观的用户体验。

命令类别概览

graph TB
    A["200+ hana-cli<br/>Commands"] --> B{Command<br/>Category}
    
    B --> C["Connection<br/>Commands"]
    B --> D["Data<br/>Manipulation"]
    B --> E["Database<br/>Inspection"]
    B --> F["Performance<br/>Analysis"]
    B --> G["Cloud<br/>Integration"]
    B --> H["HDI<br/>Management"]
    
    C --> C1["connect<br/>copy2DefaultEnv<br/>copy2Env"]
    
    D --> D1["export<br/>import<br/>dataSync<br/>tableCopy"]
    
    E --> E1["tables<br/>views<br/>procedures<br/>schemas<br/>indexes"]
    
    F --> F1["tableHotspots<br/>queryPlan<br/>alerts<br/>healthCheck"]
    
    G --> G1["btp<br/>btpInfo<br/>activateHDI"]
    
    H --> H1["containers<br/>createContainer<br/>dropContainer"]
    
    style A fill:#0070C0,color:#fff
    style B fill:#FF6B6B,color:#fff
    style C fill:#51CF66,color:#fff
    style D fill:#9D55F0,color:#fff
    style E fill:#FFD93D,color:#000
    style F fill:#F39C12,color:#fff
    style G fill:#1ABC9C,color:#fff
    style H fill:#E74C3C,color:#fff

全局标准参数

所有命令均支持以下标准连接和调试参数：

参数	别名	类型	默认值	说明
`--admin`	`-a`	boolean	false	使用管理员凭据连接（使用 default-env-admin.json）
`--conn`	—	string	—	用于覆盖 default-env.json 的连接文件名
`--disableVerbose`	`--quiet`	boolean	false	禁用详细输出，便于脚本使用
`--debug`	`-d`	boolean	false	启用调试输出以便排查问题

常用命令参数

命令分为多个类别，每个类别都有各自的标准化参数：

数据操作命令

例如 export、import、compareData、tableCopy、dataSync 等命令。

参数	别名	类型	默认值	说明
`--schema`	`-s`	string	`CURRENT_SCHEMA`	目标架构名称
`--sourceSchema`	`-ss`	string	`CURRENT_SCHEMA`	操作的源架构
`--targetSchema`	`-ts`	string	`CURRENT_SCHEMA`	操作的目标架构
`--table` / `--sourceTable`	`-t` / `-st`	string	—	表名
`--output`	`-o`	string	—	输出文件路径
`--format`	`-f`	string	见说明	输出格式（csv、json、excel、summary 等）
`--limit`	`-l`	number	1000	结果集的最大大小
`--batchSize`	`-b`、`--batch`	number	1000	处理批次大小
`--timeout`	`-to`	number	3600	操作超时时间，单位为秒（1 小时）
`--dryRun`	`-dr`、`--preview`	boolean	false	预览操作，但不提交更改
`--profile`	`-p`	string	—	数据库配置（hana、postgresql、sqlite 等）

批量操作

例如 massGrant、massUpdate、massDelete、massExport 等命令。

参数	别名	类型	默认值	说明
`--schema`	`-s`	string	—	包含对象的架构
`--object`	`-o`	string	—	对象名称模式
`--limit`	`-l`	number	1000	要处理的对象数上限
`--dryRun`	`-dr`、`--preview`	boolean	false	预览操作但不执行
`--log`	—	boolean	false	启用操作日志记录

列表／检查命令

tables、schemas、users、procedures、functions 等命令。

参数	别名	类型	默认值	描述
`--schema`	`-s`	string	`CURRENT_SCHEMA`	按 schema 筛选
`--limit`	`-l`	number	200	返回结果的最大数量
`--profile`	`-p`	string	—	数据库配置选择器

命名约定

工具遵循以下参数命名约定：

单项操作：使用单数名称（例如，schema、table、user）
源／目标操作：使用成对名称（例如，sourceSchema／targetSchema、sourceTable／targetTable）
布尔标志：使用描述性名称（例如，dryRun、includeHeaders、withGrantOption）
聚合参数：使用复数或描述性名称（例如，columns、indexes、keyColumns）

别名约定

别名遵循以下一致的模式：

单字母别名：使用参数的首字母（例如，schema 对应 -s，table 对应 -t）
扩展别名：使用有意义的缩写（例如，dryRun 对应 -dr，batchSize 对应 -batch）
不使用自指别名：参数名本身不会用作别名（例如，--schema 的别名只有 -s）
别名数量上限：参数通常最多有 2 个别名，以避免混淆

默认值

默认值经过标准化，以确保行为一致：

参数	标准默认值	备注
`schema`	`CURRENT_SCHEMA`	使用连接的当前 schema
`limit`	200（列表）／1000（数据）	根据上下文按命令配置
`batchSize`	1000	适用于所有数据操作
`timeout`	3600	长时间运行操作的标准超时时间为 1 小时
`dryRun`	false	默认提交更改；使用 `--dryRun` 可预览
`format`	"csv"（导出）／"json"（报告）	因命令类型而异
`compress`	true	默认压缩数据备份

使用示例

使用标准参数

graph LR
    A["hana-cli<br/>Command"]
    
    A --> B{Choose<br/>Operation}
    
    B --> C["List Operation<br/>tables, views, etc."]
    C --> C1["--schema<br/>-s"]
    C --> C2["--limit<br/>-l"]
    C --> C3["--profile<br/>-p"]
    C1 --> C4["Filter by schema"]
    C2 --> C5["Limit results"]
    C3 --> C6["Select DB profile"]
    
    B --> D["Data Operation<br/>export, import, etc."]
    D --> D1["--sourceTable/-st<br/>--targetTable/-tt"]
    D --> D2["--format<br/>-f"]
    D --> D3["--dryRun/-dr<br/>--preview"]
    D1 --> D4["Source/Target"]
    D2 --> D5["Output format"]
    D3 --> D6["Dry run preview"]
    
    B --> E["Batch Operation<br/>massGrant, etc."]
    E --> E1["--schema/-s"]
    E --> E2["--dryRun/-dr"]
    E --> E3["--log"]
    E1 --> E4["Target schema"]
    E2 --> E5["Safe execution"]
    E3 --> E6["Operation log"]
    
    style A fill:#0070C0,color:#fff
    style B fill:#FF6B6B,color:#fff
    style C fill:#51CF66,color:#fff
    style D fill:#9D55F0,color:#fff
    style E fill:#FFD93D,color:#000

# List all tables in current schema with preview of first 100
hana-cli tables -s myschema -l 100

# Export data with dry-run preview
hana-cli export -t CUSTOMERS -s SALES -f csv -dr

# Copy table structure without data (dry-run)
hana-cli tableCopy --sourceTable ORDERS --targetTable ORDERS_ARCHIVE --structureOnly --dryRun

# Compare schemas between databases with 2-hour timeout
hana-cli compareSchema --sourceSchema PROD --targetSchema TEST -to 7200

# Batch grant permissions (preview first)
hana-cli massGrant -s MYSCHEMA -o MYTABLE -g DEVELOPER_USER -p SELECT -dr

常见参数组合

# Preview and log operations
hana-cli massUpdate -s SCHEMA -o TABLE -c "STATUS='ACTIVE'" --dryRun --log

# Limit results and increase timeout for large datasets
hana-cli dataValidator -t BIGDATA -l 1000000 -to 7200

# Specify output format and location
hana-cli export -t CUSTOMERS -f json -o ./exports/customers.json

当前 Schema 默认值（`CURRENT_SCHEMA`）

绝大多数支持 schema 的命令现在都将 **CURRENT_SCHEMA** 作为 schema 参数的默认值。这个特殊占位符让你可以在当前数据库上下文中工作，而无需每次都显式指定 schema 名称。

支持当前 Schema 默认值的命令

以下命令类别全面支持 **CURRENT_SCHEMA** 占位符：

列表命令（30 多个命令）：

所有 schema 导航命令：tables、views、indexes、functions、procedures、triggers、sequences、synonyms、libraries、roles、objects
专用列表：partitions、columnStats、spatialData、ftIndexes、graphWorkspaces、tableHotspots、tableGroups、calcViewAnalyzer

数据操作命令（10 多个命令）：

export、import、dataProfile、dataDiff、compareData、compareSchema、tableCopy、dataSync

分析命令（10 多个命令）：

dataValidator、duplicateDetection、erdDiagram、dataLineage、referentialCheck 等

当前 Schema 示例

# Without explicit schema - uses CURRENT_SCHEMA
hana-cli tables                          # List tables in current schema
hana-cli procedures                      # List procedures in current schema
hana-cli export -t CUSTOMERS             # Export from current schema

# With explicit schema override
hana-cli tables -s PRODUCTION            # List tables in PRODUCTION schema
hana-cli procedures -s OTHER_SCHEMA      # List procedures in OTHER_SCHEMA
hana-cli export -t CUSTOMERS -s SALES    # Export from SALES schema

如需查看所有支持 **CURRENT_SCHEMA** 的命令的完整列表，请参阅 CONSISTENCY_REVIEW_COMPLETE.md 文档。

多配置文件数据库支持

所有连接数据库的命令现在都支持 --profile 参数（别名 -p），让你无需切换连接或重新定义凭据，即可使用不同的数据库配置。

支持 profile 参数的命令

以下命令支持 --profile 参数：

所有数据操作：export、import、dataProfile、dataDiff、dataSync、duplicateDetection、referentialCheck、tableCopy
列表操作：tables、views、indexes、functions、procedures、triggers、sequences、libraries、roles、objects、partitions、columnStats、spatialData、ftIndexes、graphWorkspaces、tableHotspots、tableGroups、calcViewAnalyzer
分析工具：compareData、compareSchema、dataValidator、dataLineage、erdDiagram 等

profile 参数示例

# Specify database profile
hana-cli tables --profile production     # Connect using 'production' profile
hana-cli export -t CUSTOMERS -p staging  # Export from staging environment
hana-cli dataValidator -t TABLE -p dev   # Validate data in development

# Works with other parameters
hana-cli tables -s MYSCHEMA -p prod      # List tables in schema using prod profile
hana-cli compareSchema -ss SRC -ts TGT -p target  # Schema comparison using target profile

有关数据库 profile 配置的更多详情，请参阅 utils/README.md 文档。

质量保证说明

该工具中的 200 多个命令已统一这些参数，确保参数行为一致。这种标准化确保：

可预测性：用户可以依赖各命令中一致的参数行为
易于发现：常用参数在不同场景中的用法相同
脚本编写：一致的模式让自动化脚本更易维护
减少错误：熟悉的模式可以减少错误并降低学习难度
多环境支持：profile 参数可在不同数据库实例之间无缝切换

如需详细了解 2026 年 2 月部署的所有命令一致性改进，包括更新的 30 个命令和 50 多个参数，请参阅：

CONSISTENCY_REVIEW_COMPLETE.md - 完整审查报告
COMMAND_CONSISTENCY_FIXES.md - 实现详情
COMMAND_CONSISTENCY_ANALYSIS.md - 详细审计结果

如需了解特定命令的详细信息，请使用内置帮助：

hana-cli help <command>
hana-cli <command> --help

命令

📊 命令可视化参考指南：如需查看所有命令的结构图、参数关系和快速示例，请参阅独立文档 命令结构参考指南。该文档提供可视化流程图和以下命令的详细用法模式：

连接与设置命令
数据操作（导出、导入、同步）
数据库检查与分析
HDI 容器管理
备份与恢复操作
性能分析工具
批量操作
云集成

每张命令图都展示命令语法、可用参数和典型用法模式。

单元测试

本项目包含全面的单元测试，以确保代码质量和可靠性。测试套件涵盖核心功能、命令执行和数据库操作。

有关运行测试、编写新测试和了解测试结构的详细信息，请参阅单元测试文档。

运行测试

运行测试的快速入门：

# Run all tests
npm test

# Run specific test suites
npm run test:cli      # CLI tests only
npm run test:utils    # Utils tests only
npm run test:routes   # Routes tests only

代码覆盖率

本项目使用 nyc (Istanbul) 生成代码覆盖率报告。生成代码覆盖率报告的方式如下：

# Run all tests with coverage
npm run coverage

# Run specific test suites with coverage
npm run coverage:cli      # CLI tests with coverage
npm run coverage:utils    # Utils tests with coverage
npm run coverage:routes   # Routes tests with coverage

# Generate detailed HTML coverage report
npm run coverage:report

# Check if coverage meets thresholds (80%)
npm run coverage:check

运行覆盖率测试后，请在浏览器中打开 ./coverage/index.html，查看详细的交互式覆盖率报告。

本项目的目标是让以下各项的代码覆盖率达到 80%：

行
语句
函数
分支

有关代码覆盖率配置和解读的更多信息，请参阅单元测试文档中的覆盖率部分。

跨平台支持

HANA CLI 工具旨在 Windows、Linux 和 macOS 平台上顺畅运行。本节介绍为确保行为一致而采用的跨平台功能和测试策略。

平台兼容性

该工具已在以下平台上经过测试和验证：

Windows：Windows 10 及更高版本
Linux：Ubuntu、Debian、RHEL 和其他主流发行版
macOS：macOS 10.15（Catalina）及更高版本

跨平台功能

路径处理

该工具会自动处理特定于平台的路径差异：

所有路径操作均使用 Node.js path 模块
自动检测并使用正确的路径分隔符（Unix 上为 /，Windows 上为 \）
规范化路径，确保在不同平台上的行为一致
在所有平台上均支持绝对路径和相对路径

环境变量

该工具会正确处理特定于平台的环境变量：

Windows：使用 APPDATA 存储配置文件
macOS：使用 HOME/Library/Preferences，并在不可用时回退到 HOME/Library/Application Support
Linux：使用 HOME/.config 存储配置文件

行尾

该项目使用 .gitattributes 确保行尾一致：

文本文件（.js、.json、.md 等）在仓库中使用 LF（\n）
Windows 脚本（.cmd、.bat、.ps1）使用 CRLF（\r\n）
二进制文件会得到适当处理

跨平台测试

该项目包含全面的跨平台测试：

# Run cross-platform specific tests
npm run test:platform

# Run tests tagged for Windows
npm run test:windows

# Run tests tagged for Unix systems (Linux/macOS)
npm run test:unix

持续集成

GitHub Actions CI 会在所有三个平台上运行完整的测试套件：

最新 Ubuntu：测试 Linux 兼容性
最新 Windows：测试 Windows 兼容性
最新 macOS：测试 macOS 兼容性
Node.js 版本：各平台上均测试 20.x、22.x 和 24.x

CI 工作流会验证：

在各个平台上的软件包安装
在各个平台上通过所有单元测试
特定于跨平台的测试
特定于平台的路径处理
CLI 命令执行

模拟文件系统测试

测试使用 mock-fs 模拟不同的文件系统结构：

测试可模拟 Windows、macOS 和 Linux 文件系统
无需多个操作系统环境即可验证路径处理
测试特定于平台的配置文件位置
确保在不同平台上的行为一致

开发建议

为该项目做出贡献时，请遵循以下跨平台最佳实践：

始终使用 path.join() 或 path.resolve() 处理路径，而不要进行字符串拼接
生成内容时使用 os.EOL 以采用适合平台的行尾
测试环境变量回退：Windows 使用 APPDATA、USERPROFILE，Unix 使用 HOME
根据需要使用 @windows 或 @unix 标记特定于平台的测试
在 npm 脚本中使用 cross-env，确保环境变量一致
避免在代码中硬编码路径分隔符（/ 或 \）

有关跨平台测试的更多详情，请参阅单元测试文档中的跨平台测试部分。

如何获取支持

本项目按“原样”提供：无法保证提出的问题会得到答复，或在未来版本中得到解决。

许可证

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

SAP HANA CLI

关于 SAP HANA CLI

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

SAP HANA 开发者命令行界面

⚠️ 重要通知 — 重大更新（2026 年 2 月/3 月）

📚 文档

在本地运行文档

构建生产版本

描述

支持的环境

要求 / 下载和安装

安装方法

BTP CLI 安装

关于 BTP CLI

使用 install-btp.sh 安装 BTP CLI

验证安装

安全

连接配置解析顺序

示例

项目结构和文档

Utils 文档

HTTP 路由文档

Swagger/OpenAPI 文档

Web 应用程序（Fiori Launchpad UI）

MCP（Model Context Protocol）集成

标准参数和约定

命令类别概览

全局标准参数

常用命令参数

数据操作命令

批量操作

列表／检查命令

命名约定

别名约定

默认值

使用示例

使用标准参数

常见参数组合

当前 Schema 默认值（**CURRENT_SCHEMA**）

支持当前 Schema 默认值的命令

当前 Schema 示例

多配置文件数据库支持

支持 profile 参数的命令

profile 参数示例

质量保证说明

命令

单元测试

运行测试

代码覆盖率

跨平台支持

平台兼容性

跨平台功能

路径处理

环境变量

行尾

跨平台测试

持续集成

模拟文件系统测试

开发建议

如何获取支持

许可证

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？

当前 Schema 默认值（`CURRENT_SCHEMA`）