SAP HANA CLI

SAP HANA Developer Command Line Interface

⚠️ 重要なお知らせ — 大幅な更新（2026年2月／3月）

バージョン 4.x では、Express 5 への移行、データベース接続処理の再構成、大幅なパフォーマンス改善など、重要な変更が導入されています。十分にテストを実施していますが、ご利用の環境で問題が発生する可能性があることにご注意ください。

問題が発生した場合：

• 問題を報告する： ご利用の環境と発生している問題の詳細を添えて、GitHub Issues ページから Issue を作成してください。

• 安定版に戻す： これらの大幅な変更より前の最終安定版にすぐ戻す必要がある場合は、バージョン 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 ドキュメント
• FAQ - よくある質問
• トラブルシューティング - よくある問題と解決策

ドキュメントをローカルで実行する

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 コマンドラインツールの構築方法を示すことを目的としており、特に VSCode などの SAP 製ではないツールでローカルの SAP HANA 開発を行う際に使用するよう設計されています。ローカル開発でリモート SAP HANA DB への接続によく使われる default-env.json を利用します（もちろん、ローカルの SAP HANA, express edition インスタンスでも使用できます）。汎用 SQL コンソールとして hdbsql ツールを置き換えることを意図したものではありません。このサンプルでは、多数の個別スクリプトが必要になりがちな、よく使われる複雑なコマンドを簡略化し、まとめて利用できるようにすることに重点を置いています。

紹介動画：https://youtu.be/dvVQfi9Qgog

ただし、このツールはローカル開発に限定されません。クラウドでの開発にも適しています。hana-cli ツールは、SAP Business Application Studio、Google Cloud Shell、AWS Cloud9 などのクラウドシェルからも実行できます。また、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

クラウドシェルでの実行動画：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 以降が必要です。SAP CAP 10 の推奨に従い、Node.js 24（LTS）を強く推奨します。

• 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 関連機能はすべて、SAP BTP Command Line Interface（btp CLI）がインストールされ、システムの PATH から利用できることを前提としています。

BTP CLI について

btp CLI は、SAP Business Technology Platform のリソースやサービスを管理するための SAP 公式コマンドラインツールです。グローバルアカウント、ディレクトリ、サブアカウント、エンタイトルメント、サービスインスタンスなどを管理する機能を備えています。hana-cli ツールは、開発者に使いやすいコマンドで、これらの機能の多くをラップして拡張します。

install-btp.sh を使用した BTP CLI のインストール

Linux および macOS のユーザー向けに、このリポジトリには BTP CLI のインストールを自動化する便利なインストールスクリプト install-btp.sh が含まれています。

スクリプトは次の処理を実行します。

1. SAP Development Tools のダウンロードページから最新の BTP CLI インストーラーをダウンロードします
2. インストーラーを実行可能にし、自動確認付きで実行します
3. BTP CLI を簡単に使用できるよう、シェルエイリアスを設定します
4. BTP CLI のバイナリの場所を PATH に追加します

インストールスクリプトの使用方法：

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

スクリプトを実行した後、PATH の変更を適用するために、ターミナルを再起動するか source ~/.bashrc を実行する必要がある場合があります。

注： Windows ユーザーは、SAP Development Tools のページから BTP CLI をダウンロードし、そこで各プラットフォーム向けの手順に従ってください。

インストールの確認

インストール後、次のコマンドを実行して BTP CLI が利用可能であることを確認できます。

btp --version

hana-cli ツールを使用して、BTP CLI の設定を確認することもできます。

hana-cli btp

設定されている場合、グローバルアカウント、ディレクトリ、サブアカウントなど、現在の BTP ターゲット情報が表示されます。

セキュリティ

このアプリケーションは主に、リモートの HANA DB への接続にローカル開発でよく使用される default-env.json を利用します（もちろん、ローカルの 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 を起動することもできます。

プロジェクト構成とドキュメント

Utils のドキュメント

この CLI ツールで使用される内部ユーティリティを理解または拡張したい開発者向けに、包括的なドキュメントを utils/README.md で提供しています。このドキュメントでは、次の内容を扱っています。

• コアユーティリティ：ベースモジュール、接続管理、データベースの調査、SQL インジェクション対策
• CLI 連携：BTP、Cloud Foundry、XSA CLI の連携ユーティリティ
• データベース抽象化：ファクトリーパターンによる複数データベース（HANA、PostgreSQL、SQLite）のサポート
• 使用例：ユーティリティモジュールの実践的な使用例

utils フォルダーには、データベース接続、ターミナル UI コンポーネント、セキュリティユーティリティ、国際化サポートなど、すべての CLI コマンドの基盤となる再利用可能なモジュールが含まれています。

HTTP ルートのドキュメント

hana-cli ツールには、すべての CLI 機能を RESTful HTTP エンドポイント経由で公開する組み込みウェブサーバーが含まれています。すべての HTTP ルートの詳細なドキュメントは、routes/README.md ファイルで確認できます。このドキュメントでは、次の内容を扱っています。

• 基本設定エンドポイント：CLI のプロンプトと設定を管理する GET／PUT 操作
• HANA データベースエンドポイント：HANA データベースオブジェクト（テーブル、ビュー、スキーマ、コンテナなど）の一覧表示と検査を行う完全な API
• ドキュメントエンドポイント：README と CHANGELOG への HTML 形式でのアクセス
• WebSocket のサポート：長時間実行される操作のリアルタイム通信
• 静的リソース：UI5 アプリケーションと DFA の統合

特定の CLI コマンドを -w または --web フラグ付きで実行すると、ウェブサーバーが自動的に起動し、すべての hana-cli 機能を http://localhost:3010（ポートは設定可能）への HTTP リクエスト経由で利用できるようになります。

Swagger／OpenAPI ドキュメント

hana-cli ウェブサーバーには、すべての REST API エンドポイントを対象とした包括的な Swagger／OpenAPI 3.0 ドキュメントが追加されました。これにより、すべての HTTP API を探索してテストできるインタラクティブなインターフェースが提供され、hana-cli の機能を独自のアプリケーションに簡単に統合できます。

主な機能：

• インタラクティブな API ドキュメント：リクエスト／レスポンスの完全なスキーマとともに、27 以上のドキュメント化されたエンドポイントを閲覧できます
• 試用機能：ブラウザーから API エンドポイントを直接テストできます
• 仕様の自動生成：ルートファイル内の JSDoc コメントからドキュメントが自動生成されます
• OpenAPI 3.0 標準：最大限の互換性を実現する業界標準の仕様です
• カテゴリ別の整理：エンドポイントは 10 個の論理カテゴリ（Configuration、HANA System、HANA Objects、HDI、Cloud Services など）に分類されています
• エクスポートのサポート：クライアント SDK の生成に使用できる OpenAPI JSON 仕様の生データをダウンロードできます

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 のドキュメントを参照してください。

ウェブアプリケーション（Fiori Launchpad UI）

hana-cli ツールには、SAP UI5 と Fiori Launchpad で構築された完全なブラウザーベースのインターフェースが含まれており、コマンドラインインターフェースに代わるグラフィカルな操作環境を提供します。このウェブインターフェースでは、データベース操作のための直感的なタイルベースのナビゲーションシステムを利用できます。

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

ウェブ UI は既定で http://localhost:3010 で実行され、使いやすいグラフィカルインターフェースからすべての CLI 機能にアクセスできます。すべてのウェブアプリケーション、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

主な機能：

• 段階的なツール検出 — Tier 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**	スキーマで絞り込みます
--limit	-l	number	200	返す結果の最大数です
--profile	-p	string	—	データベースプロファイルを選択します

命名規則

このツールでは、パラメーター名に関して次の規則に従います。

1. 単一操作：単数形の名前を使用します（例：schema、table、user）
2. ソース／ターゲット操作：対になる名前を使用します（例：sourceSchema／targetSchema、sourceTable／targetTable）
3. ブール値フラグ：説明的な名前を使用します（例：dryRun、includeHeaders、withGrantOption）
4. 集約パラメーター：複数形または説明的な名前を使用します（例：columns、indexes、keyColumns）

エイリアスの規則

エイリアスには、次の一貫したパターンを使用します。

1. 1 文字のエイリアス：パラメーターの最初の文字を使用します（例：schema の場合は -s、table の場合は -t）
2. 拡張エイリアス：意味のある略語を使用します（例：dryRun の場合は -dr、batchSize の場合は -batch）
3. 自己参照エイリアスは使用しない：パラメーター名自体をエイリアスとして使用しません（例：--schema のエイリアスは -s のみです）
4. エイリアスの最大数：混乱を避けるため、パラメーターのエイリアスは通常 2 個までです

デフォルト値

一貫した動作を確保するため、デフォルト値は標準化されています。

パラメーター	標準のデフォルト値	備考
schema	**CURRENT_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

現在のスキーマのデフォルト値（**CURRENT_SCHEMA**）

大多数のスキーマ対応コマンドでは、スキーマパラメーターのデフォルト値として **CURRENT_SCHEMA** を使用するようになりました。この特殊なプレースホルダーを使うと、スキーマ名を毎回明示的に指定せずに、現在のデータベースコンテキストで作業できます。

現在のスキーマのデフォルト値に対応するコマンド

次のコマンドカテゴリーは、**CURRENT_SCHEMA** プレースホルダーに完全に対応しています。

一覧表示コマンド（30 以上のコマンド）：

• すべてのスキーマナビゲーション：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 など

現在のスキーマの例

# 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 パラメーターは、以下で使用できます。

• すべてのデータ操作：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 など

プロファイルパラメーターの例

# 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

データベースのプロファイル設定の詳細については、utils/README.md のドキュメントを参照してください。

品質保証に関する注意事項

これらのパラメーターの一貫性は、ツール内の 200 を超えるすべてのコマンドで標準化されています。この標準化により、以下が実現します。

• 予測可能性：コマンド間で一貫したパラメーターの動作をユーザーが期待できます
• 見つけやすさ：共通のパラメーターが、異なるコンテキストでも同じように機能します
• スクリプト作成：一貫したパターンにより、自動化スクリプトの保守性が向上します
• エラーの削減：使い慣れたパターンにより、ミスや学習の負担が軽減されます
• 複数環境への対応：プロファイルパラメーターにより、データベースインスタンスをシームレスに切り替えられます

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 では、3 つすべてのプラットフォームで全テストスイートを実行します。

• 最新の Ubuntu：Linux との互換性をテストします
• 最新の Windows：Windows との互換性をテストします
• 最新の macOS：macOS との互換性をテストします
• Node.js のバージョン：各プラットフォームで 20.x、22.x、24.x

CI ワークフローでは、以下を検証します。

• 各プラットフォームでのパッケージのインストール
• 各プラットフォームですべてのユニットテストが成功すること
• クロスプラットフォーム固有のテスト
• プラットフォーム固有のパス処理
• CLI コマンドの実行

モックファイルシステムによるテスト

テストでは mock-fs を使用して、さまざまなファイルシステム構造をシミュレートします。

• Windows、macOS、Linux のファイルシステムをシミュレートできます
• 複数の OS 環境を用意せずにパス処理を検証します
• プラットフォーム固有の設定ファイルの場所をテストします
• プラットフォーム間で一貫した動作を保証します

開発に関する推奨事項

このプロジェクトに貢献する際は、次のクロスプラットフォームのベストプラクティスに従ってください。

1. パスの文字列連結ではなく、常に path.join() または path.resolve() を使用する
2. 生成するコンテンツでプラットフォームに適した行末を使うには、os.EOL を使用する
3. Windows（APPDATA、USERPROFILE）と Unix（HOME）の環境変数のフォールバックをテストする
4. プラットフォーム固有のテストには、適宜 @windows または @unix のタグを付ける
5. 環境変数の一貫性を保つため、npm スクリプトでは cross-env を使用する
6. コード内でパス区切り文字（/ または \）をハードコードしない

クロスプラットフォームテストの詳細については、ユニットテストのドキュメントのクロスプラットフォームテストのセクションを参照してください。

サポートを受ける方法

このプロジェクトは「現状のまま」提供されます。報告された問題への回答や、今後のリリースでの対応は保証されません。

ライセンス

Copyright (c) 2026 SAP SE or an SAP affiliate company. All rights reserved. このプロジェクトは、LICENSE ファイルに別途記載がある場合を除き、Apache Software License, v. 2 の下でライセンスされています。