EXPLAIN による実行計画の表示、
system テーブルを基盤とした監視ダッシュボードを利用できます。
はじめる前に
- LibreDB Studio を Docker (
docker run -p 3000:3000 ghcr.io/libredb/libredb-studio:latest) または Node.js 24 以降 (npx @libredb/studio) で起動し、http://localhost:3000を開きます。初回 起動時には、管理者パスワードがログに出力されます。 - LibreDB Studio を実行するマシンから ClickHouse の HTTP または HTTPS ポートにアクセスできることを確認してください。
- クエリ対象のデータベースへのアクセス権を持つ ClickHouse ユーザーを作成します。データベースブラウザを使用するには、
system.dictionariesとsystem.data_skipping_indicesに対するSELECT権限、およびDictionaryを含む 各データベースに対するdictGet権限も必要です。ダッシュボードを使用する場合は、ClickHouse の監視 に記載されているsystemテーブルに対するSELECT権限を付与してください。
uk データベースに対してクエリを実行するユーザー reader の場合は、次のようになります。
仕組み
- ブラウザがステートメントを LibreDB Studio サーバーに送信します。
- サーバーはそのステートメントを HTTP
POST /のボディとして ClickHouse に送信します。その際、default_format=JSONCompactと選択したデータベースは URL パラメータとして、認証情報は HTTP 基本認証で渡します。 - サーバーは、結果の行、ClickHouse が宣言したカラム型、ClickHouse が報告した経過時間を 返します。各ステートメントはそれぞれ独立したステートレスなリクエストとして処理され、session は固定されません。
セルフホスト型 ClickHouse に接続する
1
接続情報を準備する
ホスト、HTTP ポート (デフォルトは
8123。HTTPS を使用する場合はサーバーの HTTPS ポートで、多くの場合
8443) 、ユーザー名とパスワード、および必要に応じてデータベース名を用意してください。データベースを指定しない
接続では default が使用されます。2
接続を作成する
- サイドバーで + (New connection) を選択します。
- データベースの種類として ClickHouse を選択します。ポートには
8123が自動入力されます。 - 接続名、ホスト、ポート、ユーザー名、パスワード、および必要に応じてデータベース名を 入力します。
- HTTPS を使用する場合は、SSL / TLS を開いて
disable以外の SSL モードを選択し、Port を サーバーの HTTPS ポート (多くの場合8443) に変更します。disable以外のモードではいずれも、LibreDB Studio サーバーが信頼する CA を基にサーバー 証明書が検証されます。これはverify-systemが示す動作です。 ClickHouse Cloud や、公的に信頼された CA が発行した証明書を使用するサーバーであれば、この設定で接続できます。自己署名証明書またはプライベート CA の証明書を使用する場合は、 トラブルシューティング を参照してください。 - Test Connection を選択し、続いて Establish Connection を選択します。
clickhouse://localhost:8123/default、https://reader:secret@ch.example.com:8443/analytics) 。
https:// の URL を指定すると TLS が有効になります。3
クエリを実行する
接続を開き、エディタでステートメントを記述して実行します。データベースブラウザには、各
データベースのテーブル、ビュー、materialized view、Dictionary、ユーザー定義関数が一覧表示され、
カラム、主キーカラム、データスキッピングインデックス、オブジェクト定義も確認できます。この例では 英国不動産価格データセット を使用します。
同ガイドの手順に従って
uk.uk_price_paid にデータをロードし、接続のデータベースを uk に設定してから、
次のクエリを実行します:ClickHouse を監視する
監視ダッシュボードは、接続に設定されたユーザーの権限で以下のソースを読み取ります。
ユーザーがこれらのテーブルのいずれかに対する権限を持っていない場合や、
query_log が無効になっている場合でも、ダッシュボード全体がエラーになることはなく、該当するパネルが空のままになるだけです。system.query_log は非同期でフラッシュされるため、完了したばかりのステートメントが表示されるまでに数秒かかることがあります。
LibreDB Studio では、テーブルに対する OPTIMIZE TABLE ... FINAL の実行、テーブルまたはデータベース単位での system.parts の概要表示、KILL QUERY ... SYNC による実行中クエリの停止も行えます。これらの操作には、それぞれに対応する権限が必要です。
トラブルシューティング
接続が拒否された、またはタイムアウトした
接続が拒否された、またはタイムアウトした
リクエストを送信するのはブラウザーではなく LibreDB Studio のサーバーであるため、ホストは LibreDB Studio を実行しているマシンまたはコンテナから
接続可能である必要があります。LibreDB Studio を Docker で実行し、ClickHouse を同じマシン上で実行している場合、
localhost はホストではなくコンテナを指します。また、入力したポートがネイティブプロトコルのポート 9000 ではなく
HTTP ポートであることを確認してください。自己署名証明書またはプライベート CA の証明書で HTTPS 接続が失敗する
自己署名証明書またはプライベート CA の証明書で HTTPS 接続が失敗する
LibreDB Studio のサーバーは Node.js 上で動作しており、Node.js はサーバー証明書を自身に同梱された公開 CA の一覧と照合して検証します。
そのため、SSL / TLS に貼り付けた CA 証明書は無視され、CA をオペレーティングシステムの証明書ストアに追加するだけでも
不十分です。LibreDB Studio のサーバーを起動する際は、
NODE_EXTRA_CA_CERTS 環境変数に、CA 証明書
(自己署名の場合はサーバー自身の証明書) を含む PEM ファイルのパスを指定してください。Docker を使用する場合は、
ファイルをコンテナにマウントし、たとえば -e NODE_EXTRA_CA_CERTS=/certs/ca.pem を指定します。データベースブラウザにオブジェクトが表示されない、または Dictionary がテーブルとして表示される
データベースブラウザにオブジェクトが表示されない、または Dictionary がテーブルとして表示される
データベースブラウザは、各データベースのオブジェクトを種類別に分類するために
system.dictionaries を、
テーブルの詳細を表示するために system.data_skipping_indices を読み取ります。system.dictionaries に対する SELECT 権限がない場合は
オブジェクト一覧が読み込まれず、system.data_skipping_indices に対する SELECT 権限がない場合はテーブルの詳細が
開きません。また、ユーザーがそのデータベースに対する dictGet 権限を持っていない間は、Dictionary はテーブルとして一覧に表示されます。
始める前に に示すとおりにこれらの権限を付与し、ブラウザーを更新してください。一部のダッシュボードパネルが空になる
一部のダッシュボードパネルが空になる
ClickHouse ユーザーが、ClickHouse の監視 に記載されている
system テーブルの
いずれかを読み取れない状態です。必要なテーブルに対する SELECT 権限を付与し、再接続してください。スロークエリビューが空になる
スロークエリビューが空になる
スロークエリビューは
system.query_log を読み取りますが、クエリのログ記録が無効になっている間は何も記録されません。
ユーザーの log_queries 設定を有効にし (たとえばそのユーザーの設定プロファイルで)、いくつかクエリを実行してください。
新しいエントリはログがフラッシュされると表示されますが、これには数秒かかる場合があります。
それでもビューが空のままの場合は、クエリのログ記録がユーザー単位ではなくサーバー全体で無効になっている可能性があります。
system.query_log の説明に従い、
サーバー構成に query_log セクションが存在することを確認してください。次のステップ
- 動作の詳細については、LibreDB Studio ClickHouse プロバイダーのドキュメントを参照してください。
- サーバー構成については、ClickHouse HTTP インターフェイスのドキュメントを参照してください。