hdbsqlの使い方：SAP HANAへの接続方法とSQL実行、トラブルシューティング

SAP HANAをコマンドラインから操作するときに使われる代表的なツールが hdbsql です。SQLコンソールやSAP HANA cockpitを使えない環境でも、データベースへの接続確認、SQLの実行、結果の保存、バッチ処理などを行えます。

ただし、hdbsqlは接続先や認証情報を直接扱うため、単にコマンドを覚えるだけでは安全な運用になりません。この記事では、hdbsqlの基本的な使い方を、SAP HANA管理を担当する人が実務で確認しやすい順番で説明します。検証環境と本番環境を区別し、権限のあるユーザーだけが実行してください。

01hdbsqlとは

hdbsqlは、SAP HANAデータベースに接続してSQL文や一部の管理操作を実行するコマンドラインツールです。SAP HANAクライアントの構成要素として提供され、LinuxやWindowsなど、クライアントをインストールした環境から利用します。

主な用途は次のとおりです。

• データベースに接続できるか確認する
• SQL文を対話形式で実行する
• SQLファイルをバッチ実行する
• クエリ結果をファイルへ出力する
• スクリプトから定型的な確認処理を呼び出す

hdbsqlはアプリケーション開発用のAPIではなく、管理者や運用担当者がデータベースを直接確認するための道具です。実行するSQLによっては大量のデータを読み込んだり、データを変更したりするため、対象スキーマとトランザクションの扱いを事前に確認します。

02hdbsqlを使う前の準備

最初に、hdbsqlを実行する端末にSAP HANAクライアントが導入されていることを確認します。導入後も、実行ファイルのパスが環境変数に登録されていないと、シェルから hdbsql と入力しても見つからないことがあります。

次の項目を準備しておくと、接続エラーの切り分けが容易になります。

SAP HANAのマルチテナント構成では、システムデータベースとテナントデータベースを取り違えないことが重要です。接続先が正しくても、目的と異なるデータベースへ接続すると、想定したスキーマやビューが見つからない場合があります。

また、パスワードをコマンドライン引数に直接書く方法は、シェル履歴やプロセス情報に残る可能性があります。認証情報をコマンド履歴に残さない運用を優先し、必要に応じて対話入力、セキュアなユーザーストア、権限分離を検討してください。

03hdbsqlの接続方法

基本的な接続では、ユーザー名、パスワード、ホスト名、ポートを指定します。環境やクライアントのバージョンにより利用できるオプションが異なるため、まず hdbsql -h または hdbsql --help で手元のヘルプを確認します。

概念的な接続例は次のとおりです。

hdbsql -n <host>:<port> -u <user>

この形式では、パスワード入力を求められた後に対話セッションへ入る構成が一般的です。パスワードをコマンドに含める場合のオプションは、端末の履歴やジョブ定義に残るリスクを理解したうえで、非本番の一時的な検証に限定します。

接続後、まず現在のデータベースやユーザーを確認できるSQLを実行します。実際に使用できるSQLは権限とHANAのバージョンに依存するため、システムビューの参照権限も確認してください。

SELECT CURRENT_USER FROM DUMMY;

必要に応じて、接続先のホスト名やポートを、運用台帳やcockpitの情報と照合します。接続できたという事実だけでは、正しいテナントへ接続できたことの証明になりません。

接続文字列の考え方

-n で指定する接続先は、環境に応じてホスト名とポートの組み合わせになります。名前解決を使う環境では、DNS名が意図したアドレスへ解決されるか確認します。複数ホスト構成や高可用性構成では、単一ホストを固定することが適切とは限らないため、組織の接続方式に従ってください。

TLSを利用する環境では、サーバー証明書の検証や暗号化方式にも注意が必要です。検証を無効化して接続を通すのではなく、クライアント側の証明書配置、信頼ストア、ホスト名の一致を確認するのが基本です。

04hdbsqlでSQLを実行する方法

対話モードで接続したら、SQL文を入力して実行します。SQL文の終了記号や複数行入力の扱いは、使用するクライアントバージョンと設定によって確認が必要です。まずは読み取り専用の簡単なクエリで動作を確認します。

SELECT 1 FROM DUMMY;

テーブルを参照する場合は、スキーマ名を明示すると意図しないオブジェクト参照を避けやすくなります。業務データを対象にするSQLでは、SELECT * を避け、必要な列と件数を絞ることが安全です。

SELECT COLUMN_NAME, DATA_TYPE_NAME
FROM SYS.TABLE_COLUMNS
WHERE SCHEMA_NAME = '<SCHEMA_NAME>'
  AND TABLE_NAME = '<TABLE_NAME>';

更新、削除、DDLを実行する場合は、対象件数、ロック、トランザクション、バックアップ状況を確認します。本番環境では変更SQLを直接実行しない判断も重要です。変更が必要な場合は、承認済みの手順書、変更管理、ロールバック計画に従います。

SQL結果の読み方

大量の結果を端末へ表示すると、ログが肥大化したり、必要な情報が埋もれたりします。調査では列を絞り、ORDER BY と件数制限を使って、再現可能なクエリにします。実行時間が長い場合は、SQLそのものだけでなく、対象オブジェクトのサイズ、統計情報、ロック、メモリ、同時実行負荷も確認します。

エラーが返ったときは、エラーコード、メッセージ、実行したSQL、接続先、実行時刻を記録します。パスワードや個人情報をログへ保存しないよう、収集時にマスキングしてください。

05hdbsqlでSQLファイルを実行する方法

定型処理や複数のSQLを実行する場合は、SQLをファイルに保存してhdbsqlへ渡します。一般的な形は次のとおりです。

hdbsql -n <host>:<port> -u <user> -I query.sql

query.sql の内容には、検証対象を明確にするコメント、必要なSQL、結果確認用のSQLを含めます。ファイルはバージョン管理の対象にし、レビューで変更内容を確認できるようにします。ただし、パスワードや本番固有の秘密情報はファイルへ直接書き込まないでください。

バッチ実行では、SQLの途中でエラーが発生した場合に後続処理が続くのか、終了コードがどのように返るのかを確認します。シェルスクリプトから呼び出す場合は、終了コードを検査し、失敗時にアラートや処理停止へつなげます。

hdbsql -n <host>:<port> -u <user> -I query.sql
status=$?
if [ "$status" -ne 0 ]; then
  echo "hdbsql failed: $status" >&2
  exit "$status"
fi

本番ジョブでは、二重実行への対策、タイムアウト、ログの保管期間、実行ユーザーの権限を定義します。バックアップやリカバリに関係する確認では、対象システム、世代、完了時刻を必ず照合し、SQLの結果だけで完了と判断しないようにします。

06hdbsqlの結果を保存する方法

調査結果を保存するときは、端末への表示とファイルへの出力を分けて考えます。利用できる出力オプションや区切り文字は、クライアントのヘルプで確認してください。CSVのような形式で保存する場合は、列内の改行、カンマ、文字コード、NULL値の表現を決めておくと後処理で混乱しません。

保存したログには、接続先、ユーザー、実行時刻、SQLの識別子を付けると追跡しやすくなります。一方で、業務データや個人情報を含む結果は、アクセス制御と保管期限を適用します。結果ファイルを共有する前に、機密情報が含まれていないか確認してください。

07hdbsqlを終了する方法

対話セッションを終了するときは、使用しているクライアントで案内されている終了コマンド、または標準的なEOF操作を使います。終了前に、未完了のSQL、未コミットの変更、実行中の処理がないかを確認します。

読み取りだけの調査でも、長時間のカーソルやトランザクションが残ると、リソースや運用に影響することがあります。終了後は、必要に応じてセッションが残っていないか、監視画面や管理用ビューで確認します。

08hdbsqlのよくあるエラーと切り分け

hdbsqlのエラーは、クライアント、ネットワーク、認証、データベース、SQLのいずれかに分けると調査しやすくなります。最初からSQLを変更するのではなく、接続の段階を分けて確認します。

コマンドが見つからない場合

hdbsql: command not found のようなメッセージが出る場合、クライアントが未導入か、実行パスが設定されていない可能性があります。インストール先を確認し、対象ユーザーのシェル環境へ正しいパスを設定します。複数バージョンのクライアントがある場合は、意図した実行ファイルを明示します。

接続できない場合

まずホスト名の名前解決、対象ポートへのネットワーク到達性、データベースが稼働中かを確認します。SAP HANAの起動状態を確認する必要がある場合は、運用手順と監視情報を併用し、無断で再起動しないでください。接続先を誤ると、エラーではなく別環境への正常接続になるため、接続後の識別情報も確認します。

権限エラーの場合

認証成功と権限付与は別の問題です。対象オブジェクトの所有者、必要なシステム権限、オブジェクト権限を確認し、管理者ロールを安易に付与しないようにします。ユーザー管理の変更は、監査可能な申請と承認のもとで実施します。権限設計の整理には、SAP HANAユーザー権限の確認方法も役立ちます。

09hdbsqlを安全に運用するチェックリスト

実行前後に、次の項目を確認します。

• 接続先が想定したシステムとテナントである
• 実行ユーザーの権限が目的に対して過剰ではない
• パスワードを履歴、スクリプト、ログに残していない
• 本番変更の場合、承認、バックアップ、ロールバックを確認した
• 大量取得や長時間実行の影響を評価した
• SQLファイルをレビューし、対象環境を明示した
• 終了コードとエラー内容を監視へ連携した
• 結果ファイルの機密性、保管期限、アクセス権を確認した

hdbsqlは、障害対応や定型運用を効率化できる一方、強い権限で使うほど影響範囲が広くなります。運用手順には、実行者、対象環境、事前確認、実行コマンド、期待結果、異常時の連絡先を明記してください。

10まとめ

hdbsqlを使うと、SAP HANAへコマンドラインから接続し、SQLを対話形式またはファイル形式で実行できます。基本の流れは、クライアント確認、接続先確認、読み取りSQLでの疎通、必要な処理の実行、結果と終了コードの確認です。

特に重要なのは、接続できたことと、正しいデータベースへ安全に接続できたことを区別することです。認証情報の保護、最小権限、変更管理、ログのマスキングを組み合わせることで、hdbsqlを日常運用と障害調査の両方で扱いやすくなります。SAP HANAのバックアップやリカバリを確認する場合は、SQLの結果だけでなく、運用基盤のステータスや正式な手順も併せて確認してください。

11FAQ

Q. hdbsqlはどこから入手できますか？

A. SAP HANAクライアントの一部として提供されます。利用環境に適合したクライアントを、組織のソフトウェア配布手順とSAPの案内に従って導入してください。導入後は、クライアントとデータベースの互換性も確認します。

Q. hdbsqlでパスワードを指定してもよいですか？

A. 技術的に指定できる場合でも、シェル履歴、ジョブ定義、プロセス一覧、ログへ漏れるリスクがあります。対話入力やセキュアな認証情報管理を優先し、どうしても自動化する場合は、アクセス制御と秘密情報のローテーションを設計してください。

Q. hdbsqlで接続できるのにテーブルが見つかりません。なぜですか？

A. テナント、ユーザー、スキーマ、オブジェクト名の大文字小文字、権限のいずれかが想定と異なる可能性があります。現在のユーザーと接続先を確認し、スキーマ名を明示したSQLで段階的に調査します。

Q. SQLファイルを本番環境で実行するときの注意点は何ですか？

A. 対象環境、実行ユーザー、変更内容、トランザクション、ロールバック、タイムアウト、終了コードを事前に定義します。レビュー済みのファイルだけを使用し、結果とログを監査可能な形で保管してください。