mcpField
A
altinity-expert-clickhouse-connection

altinity-expert-clickhouse-connection

github.com/altinityデータ・データベース1794 回インストール6 週間前に更新
リポジトリ

altinity-expert-clickhouse-connection について

altinity-expert-clickhouse-connectionは、Altinity ClickHouseエキスパートスキル群の接続準備スキルです。接続を検証し、接続方式とクラスタモードを判定してサーバー情報を集め、後続スキル用の時間範囲を定めます。

主な機能

  1. 01MCPまたはclickhouse-client方式の選択
  2. 02接続検証とサーバー情報の収集
  3. 03クラスタまたは単一ノードの判定
  4. 04分析対象期間の設定
  5. 05クエリパックの実行と報告の案内

活用シーン

  1. 01ClickHouseのヘルスチェック準備
  2. 02クエリ実行前のクラスタ確認
  3. 03診断対象期間の設定

MCP 対応

利用可能なClickHouse MCPツールがあれば、1回の呼び出しにつき1つのSQL文を実行します。ない場合は、シェルからclickhouse-clientを使用できます。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/altinity/altinity-skills --skill altinity-expert-clickhouse-connection

インストール後、Claude Code で/altinity-expert-clickhouse-connectionを入力して読み込まれたか確認します。

詳細

接続、クラスター、時間範囲

ほかの altinity-expert-clickhouse-* スキルを使う前に、これを実行してください。後続のすべてのスキルで再利用する情報、つまり接続モード、クラスター名（または単一ノード）、ClickHouse のバージョン、Keeper の有無、時間範囲を取得します。

ステップ 1：接続モードを選択する

利用可能なツールを次の順序で確認し、最初に該当したものを選択してください。

  1. MCP モード：名前に clickhouse と query、execute、sql のいずれかを含むツール（例：clickhouse_execute_query、mcp__clickhouse__execute_query）。1 回の呼び出しにつき、SQL ステートメントを正確に 1 つ送信してください。ClickHouse MCP サーバーが複数ある場合は、どれを使うかユーザーに尋ねてください。
  2. Exec モード：シェルツールと clickhouse-client（または clickhouse client）。ユーザーが指定した接続フラグ（--host、--port、--user、--password、--secure）のみを使用してください。環境変数から認証情報を推測してはいけません。--query "<statement>" を使い、呼び出しごとに 1 つのステートメントを実行してください。--queries-file や --multiquery は使用しないでください。
  3. どちらも該当しない場合：そこで停止し、ClickHouse への接続方法をユーザーに尋ねてください。ソフトウェアをインストールしたり、ヘルパースクリプトを作成したりしないでください。

ステップ 2：接続を確認し、ヘッダー情報を収集する

次のステートメントを実行してください。マクロや Keeper のないスタンドアロンサーバーでも、クラスターでも動作します。

SELECT
    hostName() AS hostname,
    version() AS version,
    (SELECT substitution FROM system.macros WHERE macro = 'cluster') AS cluster_macro,
    (SELECT groupUniqArray(cluster) FROM system.clusters WHERE NOT is_local) AS candidate_clusters,
    (SELECT count() FROM system.tables WHERE database = 'system' AND name = 'zookeeper_connection') AS has_keeper,
    formatReadableTimeDelta(uptime()) AS uptime,
    formatReadableSize((SELECT value FROM system.asynchronous_metrics WHERE metric = 'OSMemoryTotal')) AS os_memory_total

認証エラーまたはネットワークエラーが発生した場合は、そこで停止し、接続情報をユーザーに尋ねてください。推測した認証情報で再試行してはいけません。

ステップ 3：クラスターのモードを決定する

  • cluster_macro が空でない → クラスター モード。すべてのクエリパックで '{cluster}' を記載どおりに残してください。サーバーがマクロを展開します。
  • cluster_macro が空で、candidate_clusters が空でない → 使用するクラスターをユーザーに尋ねてから、各ステートメントの '{cluster}' をその名前に置き換えて実行してください。
  • 両方が空 → 単一ノード モード。各ステートメントで clusterAllReplicas('{cluster}', system.<table>) を system.<table> に置き換えてください。

has_keeper = 0 は Keeper/ZooKeeper がないことを意味します。-- @requires keeper とマークされたステートメントをすべてスキップし、レプリケーションと ON CLUSTER のチェックは該当なしとして報告してください。

ステップ 4：時間範囲を確定する

  • ユーザーが時間範囲を指定した場合は、その範囲をそのまま使用してください。
  • それ以外の場合は、過去 24 時間を使用してください（event_time >= now() - INTERVAL 24 HOUR）。クエリパックは相対的な時間範囲をすでに使用しています。ユーザーに確認せずに範囲を広げないでください。

クエリパックの実行方法（すべてのスキルに適用）

  1. スキルのディレクトリから各パックファイルを読み込みます（スキルローダーがディレクトリのパスを出力します）。
  2. ステートメントをファイル単位ではなく、1 つずつ実行してください。ステートメントは ; で終わり、-- @check <id> <title> ヘッダーで始まります。結果には ID を付けてください。
  3. -- @requires に従ってください。指定されたテーブルがない場合、keeper が必要で has_keeper = 0 の場合、またはバージョン条件を満たさない場合は、そのステートメントをスキップします。スキップした ID と理由を一覧にしてください。
  4. ステップ 3 で決定した {cluster} をそのまま使用してください。その他の {placeholder} はテンプレート変数です。実際の値に置き換えるか、ステートメントをスキップしてください。
  5. エラーが発生した場合は、チェック ID とエラーの先頭行を記録してから、次のステートメントに進んでください。UNKNOWN_IDENTIFIER の場合に限り、DESCRIBE TABLE system.<table> を実行し、存在しないカラムを取り除いてください。
  6. severity カラムは、その行の判定結果です。その値をそのまま転記し、再評価しないでください。

レポートヘッダー

すべてのレポートは、ステップ 2 で取得した情報を入力した次の表から始めてください。

接続モードクラスターClickHouse のバージョンKeeper時間範囲
MCP または clickhouse-clientマクロの値、選択したクラスター、または「単一ノード」バージョンはい／いいえ使用した時間範囲

次のスキル

  • 問題の領域が不明、または全般的なヘルスチェック → スキル altinity-expert-clickhouse-overview を読み込む
  • 症状が特定されている → 該当する専門スキル（メモリ、マージ、レプリケーション、取り込み、レポート、ストレージなど）を読み込む

コメント

Markdown 対応